Skip to content
CAI
Software that uses CAICheck a score

zio/zio-prelude

61.2

Adequate · 6 November 2026

31k

lines of production code

Scala

primary language

4

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

What this system is

This system is the ZIO Prelude, a functional programming library that provides a comprehensive set of type classes, algebraic structures, and data types for the ZIO ecosystem. It enables developers to write generic, law-abiding code by offering abstractions for effects, validation, recursion schemes, and parallel collections, with deep integration into ZIO 2. The library supports multiple Scala versions (2.12, 2.13, and 3) through version-specific implementations and macro-based derivation for features like debugging and newtype validation.

How it got here

2020 — ZIO 2 migration and infrastructure modernization

13 changes.

The project underwent a comprehensive modernization to support ZIO 2, introducing new type classes, data types, and coherent derivation instances while upgrading the build system and CI infrastructure. Legacy components, including old website configurations and debug utilities, were removed to streamline the codebase and developer experience.

2021 — Algebraic structures and Scala 3 support

20 changes.

This period focused on expanding the ZIO Prelude with new algebraic and categorical type classes, including lattice and ring laws, alongside recursion schemes like Folder and Unfolder. Significant effort was dedicated to enhancing Scala 3 compatibility through native implementations for debugging, equality derivation, and newtype validation, while also adding support for Scala parallel collections. The work was underpinned by comprehensive property-based testing and law verification to ensure the correctness of these new mathematical structures and platform-specific features.

2022–2024 — Scala 2.12 compatibility and Magnolia integration

8 changes.

This period focused on resolving Scala 2.12 compatibility issues by introducing version-specific implementations for Newtype, Subtype, and IterableOnce abstractions to avoid cyclic alias errors. It also added automatic Debug typeclass derivation via Magnolia and optimized the ZPure execution engine's internal stack implementation for better performance.

Features

Add Prelude type-class instances for Scala parallel collections

The \scala-parallel-collections\ module now provides \zio.prelude\ type-class instances for Scala's immutable parallel collections (\ParMap\, \ParSeq\, and \ParSet\). Users can now leverage prelude features such as equality, hashing, ordering, and flattening on these parallel data structures, with specific implementations handling the unique constraints of parallel collections (e.g., using object equality for keys in \ParMap\).

scala-parallel-collections/src/main · high confidence

Add newtype wrappers for arithmetic, logical, and error types

The \zio.prelude.newtypes\ package now provides a set of newtype wrappers to enforce type safety and semantic meaning for common operations. This includes \Sum\ and \Prod\ for additive and multiplicative arithmetic, \Or\ and \And\ for logical disjunction and conjunction, and \Natural\ for non-negative integers with safe arithmetic operations (plus, minus, times) that handle overflow by capping at \Int.MaxValue\. Additionally, newtypes like \Failure\, \FailureIn\, and \FailureOut\ are introduced to represent error states, while \First\, \Last\, \Min\, and \Max\ provide wrappers for selection operations.

core/shared/src/main/scala-2/zio/prelude/newtypes · high confidence

Added ConsoleUtils for terminal text styling

A new ConsoleUtils object has been added to the shared macros module, providing helper methods to apply ANSI escape codes for text styling (such as underlined, green, yellow, red, blue, magenta, cyan, dim, and bold) in console output.

macros/shared/src/main/scala · high confidence

Added Folder and Unfolder types for recursion schemes

New Folder and Unfolder types have been added to the zio.prelude.recursive package to support recursion schemes. Folder acts as a catamorphism (folding) function that reduces a recursive structure, while Unfolder acts as an anamorphism (unfolding) function that builds a recursive structure. Both types include a zip method for combining operations and an Invariant type class instance for mapping between equivalent types.

core/shared/src/main/scala/zio/prelude/recursive · high confidence

Added Scala 2 examples for SmartTypes and custom assertions

New example files have been added for Scala 2.12/2.13 demonstrating the use of SmartTypes (Subtype and Newtype) with custom assertions, including regex-based validation for types like Email and MyRegex, as well as a custom function example using assertCustom.

examples/shared/src/main/scala-2 · high confidence

Added lattice and ring law specifications for ZIO Prelude

New law definitions have been added to the \experimental-laws/shared\ module to support lattice and ring-like structures in ZIO Prelude. This includes absorption laws (join and meet), annihilation laws, distributive laws (for both absorption and product operations), and logical laws such as excluded middle, non-contradiction, and involution. These additions provide the formal verification basis for instances of \AbsorptionEqual\, \AnnihilationEqual\, \DistributiveAbsorptionEqual\, \DistributiveProdEqual\, \ExcludedMiddleEqual\, \InvolutionEqual\, and \NoncontradictionEqual\.

experimental-laws/shared · high confidence

Added property-based testing laws and generators for ZIO Prelude

The \laws/shared\ module now includes a comprehensive suite of property-based tests and data generators for ZIO Prelude type classes. This adds law definitions for \Equal\, \Hash\, \Ord\, \PartialOrd\, \Associative\, \Commutative\, \Identity\, \Inverse\, \Idempotent\, \Covariant\, \Contravariant\, \ForEach\, \NonEmptyForEach\, \AssociativeBoth\, \CommutativeBoth\, \IdentityBoth\, \AssociativeEither\, \CommutativeEither\, \IdentityEither\, \AssociativeFlatten\, and \IdentityFlatten\. It also introduces \GenFs\ and \Gens\ to provide generators for Prelude types (such as \Natural\, \ParSeq\, \NonEmptyList\, \Validation\, and \These\) and standard Scala types, enabling users to verify that their custom type class instances satisfy the required mathematical laws.

laws/shared · high confidence

Automatic derivation of Debug typeclass via Magnolia

Users can now automatically derive the Debug typeclass for custom types in the ZIO Prelude using Magnolia macros. This change adds Scala 2 and Scala 3 specific implementations (DeriveDebug.scala) that handle value classes, objects, case classes, and sealed traits, allowing for automatic generation of debug representations without manual boilerplate.

magnolia/shared · high confidence

Introduction of core Prelude data types and effect systems

This release introduces the foundational types and effect systems for zio-prelude. It adds \ZPure\, a purely functional effect type combining environment, state, failure, and logging, along with \ZValidation\ for accumulating errors and logs. New data types include \These\ (Left, Right, or Both), \ParSeq\ for parallel/sequential event modeling, \Optional\ as a nullable wrapper, and \NonEmptyList\ with extended collection operations. The release also provides \Debug\ for structured value rendering, \Ord\ for total ordering, and \Divariant\ for function variance, alongside a JMH benchmark for \ZPure\.

repository · high confidence

New coherent derivation instances for ZIO Prelude type classes

The \zio.prelude.coherent\ package now provides a new file \coherent.scala\ containing automatic derivation instances that combine ZIO Prelude type classes with \DeriveEqual\. This includes traits and objects for \AssociativeBoth\, \AssociativeEither\, \AssociativeFlatten\, \CommutativeBoth\, \CommutativeEither\, \CommutativeIdentity\, \Covariant\, \Contravariant\, and \IdentityFlatten\, allowing users to automatically derive \Equal\ instances for types that already implement these algebraic structures. Specifically, \CovariantIdentityBoth\ now includes a \collectM\ method and an optimized \forEach\ implementation using \foldLeft\ and \zipWith\ for better performance on collections.

core/shared/src/main/scala/zio/prelude/coherent · high confidence

New experimental algebraic and categorical type classes

The \experimental\ package now includes a suite of new type classes and syntax extensions for algebraic structures and category theory. This adds \Absorption\ (with \or\/\and\ operations), \DistributiveProd\ (with \sum\/\prod\), and their combinations like \Annihilation\, \Complement\, \Divide\, \PartialDivide\, and \Subtract\, along with logical structures such as \ExcludedMiddle\, \Noncontradiction\, and \Involution\. It also introduces categorical composition traits including \BothCompose\, \ApplicationCompose\, and \EitherCompose\ with corresponding syntax for currying, uncurrying, and combining functions. Coherent instances are provided in the \coherent\ sub-package to ensure consistency with \Equal\.

experimental/shared · high confidence

Scala 3 examples for Smart Types and Validators

Added new Scala 3-specific example files demonstrating Smart Types and Validators. SmartTypes.scala shows how to define custom subtypes (Natural, Age, Email) and newtypes (MyRegex, Palindrome, NonEmptyString) using inline assertions with operators like greaterThanOrEqualTo, matches, and equalTo. validators.scala provides a concrete example of a custom validator (PalindromeValidator) for string validation.

examples/shared/src/main/scala-3 · high confidence

Scala 3-specific newtype definitions for ZIO Prelude

A new Scala 3-specific package has been added to define a suite of newtypes for the ZIO Prelude, including arithmetic wrappers (Sum, Prod, Natural), logical operators (Or, And, AndF, OrF), and error-handling types (Failure, FailureIn, FailureOut). This change introduces Scala 3-specific implementations for these types, likely leveraging Scala 3 features such as inline assertions and macros, to support the library's migration to Scala 3.

core/shared/src/main/scala-3/zio/prelude/newtypes · high confidence

ZIO Prelude restructured with new type classes and ZIO 2 integration

The ZIO Prelude library has been significantly reorganized and expanded to support ZIO 2. This update introduces a comprehensive hierarchy of new type classes including Associative, AssociativeBoth, AssociativeCompose, AssociativeEither, AssociativeFlatten, Bicovariant, Commutative, CommutativeBoth, CommutativeEither, and Contravariant. It also adds new data types like AnyType and Const, and integrates ZIO 2 specific types such as ZEnvironment, ZLayer, ZSTM, ZSink, and ZStream into the prelude's type class instances. This provides users with a more robust and standardized set of functional programming abstractions aligned with the ZIO 2 ecosystem.

core/shared/src/main/scala/zio/prelude · high confidence

Removals

Removal of legacy Debug, Equal, and HelloWorld components

The legacy \Debug\, \Equal\, and \HelloWorld\ source files have been removed from the \zio.prelude\ package. This deletion eliminates the old \DebugSyntax\ and \EqualSyntax\ implicit classes, along with the \package.scala\ definitions that previously exposed these syntax extensions to users. The \HelloWorld.scala\ example file, which contained stubbed \JsonCodec\ logic and ZIO application scaffolding, is also removed, cleaning up the public API surface.

src/main · high confidence

Removal of legacy Docusaurus 1 website configuration

The legacy Docusaurus 1-based website structure has been removed, specifically deleting the homepage component (\website/pages/en/index.js\), the sidebar navigation configuration (\website/sidebars.json\), and the main site configuration file (\website/siteConfig.js\). This change eliminates the previous static site generation setup for the ZIO Prelude documentation, which previously relied on these specific files to render the home splash, navigation links, and global site metadata.

website · high confidence

Behavioural changes

Major updates to build tooling, CI, and documentation

The project has upgraded its build infrastructure and developer experience: the SBT launcher has been updated from version 0.13.18 to 1.7.1, and the Node.js version is now pinned to 20.9.0. Scalafmt has been upgraded to version 3.10.6 with updated configuration for dialect and docstrings, and a new \.scalafix.conf\ has been introduced to enforce import organization and other code hygiene rules. CI has migrated from CircleCI to GitHub Actions, and the README has been replaced with an auto-generated version that includes installation instructions and examples. Additionally, the \.gitignore\ has been updated to exclude VS Code and BSP files, and Mergify configuration has been added to automate dependency PR handling.

(repo-wide) · high confidence

Newtype and Subtype type aliases resolved for Scala 2.12+ compatibility

To resolve cyclic alias errors in Scala 2.12+, the library introduces version-specific implementations for the Newtype and Subtype abstractions. New files \NewtypeVersionSpecific.scala\ and \Subtype.scala\ define the \Newtype\ type alias and the \Subtype\ abstract class specifically for the Scala 2.12+ source directory, ensuring that the type system constraints (such as \Subtype\ extending \Newtype\ with a refined \Type\) compile correctly without circularity issues on these Scala versions.

core/shared/src/main/scala-2.12+ · high confidence

Optimized internal stack implementation for ZPure

The ZPure execution engine now uses a new, lightweight internal Stack implementation to improve performance. This change introduces a specialized data structure optimized for the specific usage patterns of ZPure, replacing previous mechanisms with a more efficient array-based approach that reduces overhead during pure computations.

core/shared/src/main/scala/zio/prelude/fx · high confidence

The custom \Footer.js\ component, which previously rendered the site's footer with links to GitHub, Discord, and Scaladoc, has been deleted from the website core. This change removes the custom footer implementation, likely shifting the site to a default footer provided by the underlying documentation framework.

website/core · high confidence

Removed website static assets and custom CSS

The website's static assets have been cleaned up by deleting the custom CSS file (\website/static/css/custom.css\) and several SVG illustration files (\undraw\_code\_review.svg\, \undraw\_online.svg\, \undraw\_open\_source.svg\, and \undraw\_operating\_system.svg\). This removes the custom styling rules and the specific vector images that were previously served from the static directory.

website/static · high confidence

Scala 2-specific Newtype and version-specific trait implementations

This change introduces Scala 2-specific implementations for the Newtype system and related version-specific traits. It adds \DebugVersionSpecific\ and \EqualVersionSpecific\ traits for Scala 2, and provides a dedicated \Newtype.scala\ implementation for Scala 2 that includes support for Smart Newtypes with compile-time assertions, subtype creation, and class tag handling. This ensures that Newtype functionality, including validation and type class derivation, works correctly on Scala 2, complementing the existing Scala 3 implementation.

core/shared/src/main/scala-2/zio/prelude · high confidence

Scala 2.12 compatibility layer for IterableOnce and ForEach

Added Scala 2.12-specific source files to provide compatibility for \IterableOnce\ and \ForEach\ operations. The new \IterableOnceCompat\ trait supplies \iterator\ and \knownSize\ methods to mimic Scala 2.13's \IterableOnce\ interface, while \InvariantVersionSpecific\ introduces an implicit \ForEach\ derivation for \Iterable\ types using \CanBuildFrom\, enabling collection-based effects to work correctly on Scala 2.12.

core/shared/src/main/scala-2.12 · high confidence

Scala 2.13+ specific ForEach derivation and IterableOnce compatibility

Added Scala 2.13+ specific implementation files to support the \ForEach\ type class for \Iterable\ types and provide a compatibility shim for \IterableOnce\. The new \InvariantVersionSpecific\ trait derives \ForEach\ from \Iterable\ using \BuildFrom\, enabling collection operations within the prelude for Scala 2.13+ users, while \IterableOnceCompat\ ensures compatibility with the \IterableOnce\ trait introduced in Scala 2.13.

core/shared/src/main/scala-2.13+ · high confidence

Scala 3-specific prelude implementations for debugging, equality derivation, and newtypes

This change introduces a set of Scala 3 version-specific files in the \zio.prelude\ package to leverage Scala 3 features. It adds \DebugVersionSpecific\ to provide \Debug\ instances for \IArray\, \EqualVersionSpecific\ to automatically derive \Equal\ instances for product and sum types using Scala 3's \Mirror\, and \Liftables\/\Macros\ to enable compile-time validation of assertions and improved error messages for newtypes. Additionally, it defines \Newtype.scala\ and \Validator.scala\ to support custom newtype validation with compile-time checks and class tag support, replacing or augmenting previous Scala 2/3 shared implementations with Scala 3-native code.

core/shared/src/main/scala-3/zio/prelude · high confidence

Support for new string and regex assertion operators in Scala 2 macros

The Scala 2 macro implementation in \Liftables.scala\ has been updated to support new assertion capabilities, specifically \startsWithIgnoreCase\ and \endsWithIgnoreCase\ for strings, as well as various regex operators. This change enables the macro to correctly lift and unlift these new assertion types during compile-time code generation, allowing users to utilize these enhanced pattern-matching and string-checking features in their Scala 2 projects.

macros/shared/src/main/scala-2 · high confidence

Fixes

Fixes cyclic alias error in newtype examples

Resolves a compilation error caused by cyclic aliases when nesting newtypes. The example code now correctly defines a \GenericItemId\ newtype based on \UUID\ and a \SpecificItemId\ subtype, ensuring that the \GreatTypeclass\ implicit resolution works without hitting Scala 2's cyclic reference restrictions.

examples/shared/src/main/scala-2.12+ · high confidence

Test coverage

Added JMH benchmarks for ZIO Prelude collection and state operations; Added Scala 2.12/2.13-specific test types for custom Newtype assertions; Added Scala 3 tests for derivation and newtype validation; Added comprehensive test suite for ZIO Prelude typeclass laws and utilities; Added comprehensive test suite for ZPure; Added experimental prelude law tests; Added law-based tests for Scala parallel collections; Added test fixtures for newtype case-insensitive assertions; Added test for FutureCommutativeEither behavior; Added tests for Magnolia-based Debug derivation; Added tests for Optional as IterableOnce; Removed HelloWorldSpec test suite.

Dependencies

Major build system and dependency upgrades

The project's build infrastructure has been significantly modernized: sbt has been upgraded from 1.3.7 to 1.13.0, and Scala versions have been updated to 2.12.21, 2.13.16, and 3.3.8. Several SBT plugins have been upgraded or replaced, including sbt-scalafix (0.14.9), sbt-buildinfo (0.13.2), sbt-mdoc (2.9.2), sbt-scalajs (1.20.1), and sbt-scala-native (0.5.12), while sbt-bloop was removed in favor of other tooling. The build configuration also introduces new compiler options for Scala 3, enables fatal warnings in CI, and adds support for ZIO 2 via the magnolia library derivation.

project · high confidence

Migrate CI to zio-sbt-ci and update ZIO to 2.1.23

The build system has been migrated to use the zio-sbt-ci plugin, replacing the previous manual GitHub Actions workflow and Docusaurus-based website setup. This change updates the ZIO dependency to version 2.1.23 and configures the CI pipeline to run on Ubuntu 22.04 with specific JDK 11 and 21 test jobs, while also fixing dependency bot auto-merge configurations for Scala Steward. The website documentation is now managed via a simplified package structure, and the build script introduces new sbt aliases for formatting, linting, and platform-specific testing (JVM, JS, Native).

(dependencies) · 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 69 → 61 (-7.7)
  • Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.

Lenses

  • Code Health 72 → 72 (+0.0)
  • Architecture 92 → 91 (-1.2)
  • Maturity 65 → 65 (+0.0)
  • Readiness 86 → 86 (-0.1)
  • Security 66 → 49 (-17.0)
  • Performance 80 → 80 (+0.0)

Resolved (1)

  • Off-boarding risk: anonymized user #1

New (2)

  • Off-boarding risk: anonymized user #1
  • Outdated: org.scala-lang.modules:scala-parallel-collections_2.13

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

zio/zio-prelude 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 6 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 1a32c82e9461a21d8c7682d63566bd10a1413b8e — 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-60d1b390edf0.