or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

alternative-laws.mdbifunctor-laws.mdcategory-laws.mdcommutative-laws.mdcomonad-laws.mdcore-laws.mderror-laws.mdindex.mdparallel-laws.mdtesting-utilities.mdtraversal-laws.md
tile.json

tessl/maven-org-typelevel--cats-laws_native0-5_2-13

Laws for testing type class instances in the Cats functional programming library for Scala

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.typelevel/cats-laws_native0.5_2.13@2.12.x

To install, run

npx @tessl/cli install tessl/maven-org-typelevel--cats-laws_native0-5_2-13@2.12.0

index.mddocs/

Cats Laws

A comprehensive library providing laws for testing type class instances in the Cats functional programming library for Scala. The cats-laws package ensures that type class implementations satisfy the mathematical laws they should uphold, providing property-based testing capabilities for functional programming abstractions.

Package Information

  • Package Name: cats-laws
  • Package Type: maven
  • Language: Scala
  • Installation: libraryDependencies += "org.typelevel" %% "cats-laws" % "2.13.0"

Core Imports

import cats.laws._
import cats.laws.discipline._

For ScalaCheck testing:

import cats.laws.discipline.FunctorTests
import org.scalacheck.Prop._

Basic Usage

import cats.laws.discipline.MonadTests
import cats.syntax.all._
import org.scalacheck.{Arbitrary, Gen}
import org.scalatest.funsuite.AnyFunSuite
import org.scalatestplus.scalacheck.Checkers

class OptionLawTests extends AnyFunSuite with Checkers {
  
  // Test that Option satisfies Monad laws
  checkAll("Option.MonadLaws", MonadTests[Option].monad[Int, Int, String])
  
  // Test that List satisfies Functor laws  
  checkAll("List.FunctorLaws", FunctorTests[List].functor[Int, Int, String])
}

Architecture

The cats-laws library is organized into two main packages:

  • cats.laws - Contains trait definitions for mathematical laws that type classes must satisfy
  • cats.laws.discipline - Contains ScalaCheck-based test implementations for property-based testing

Each type class in Cats has corresponding Laws and Tests classes following a consistent pattern:

  1. *Laws[F[_]] traits define the mathematical properties as methods returning IsEq[T]
  2. *Tests[F[_]] traits provide ScalaCheck property tests via RuleSet objects
  3. Companion objects provide convenient apply methods for instantiation

Capabilities

Core Laws and Testing

The foundational laws for basic type class hierarchies including Functor, Applicative, and Monad.

trait FunctorLaws[F[_]] extends InvariantLaws[F] {
  implicit def F: Functor[F]
  def covariantIdentity[A](fa: F[A]): IsEq[F[A]]
  def covariantComposition[A, B, C](fa: F[A], f: A => B, g: B => C): IsEq[F[C]]
}

trait MonadLaws[F[_]] extends ApplicativeLaws[F] with FlatMapLaws[F] {
  def monadLeftIdentity[A, B](a: A, f: A => F[B]): IsEq[F[B]]
  def monadRightIdentity[A](fa: F[A]): IsEq[F[A]]
}

Core Laws and Testing

Alternative and MonoidK Laws

Laws for alternative operations and monoid structures on type constructors.

trait AlternativeLaws[F[_]] extends NonEmptyAlternativeLaws[F] with MonoidKLaws[F] {
  def alternativeRightAbsorption[A, B](ff: F[A => B]): IsEq[F[B]]
  def alternativeLeftDistributivity[A](fa: F[A], fa2: F[A], f: A => A): IsEq[F[A]]
}

trait MonoidKLaws[F[_]] extends SemigroupKLaws[F] {
  implicit def F: MonoidK[F]
}

Alternative and MonoidK Laws

Traversal Laws

Laws for traverse and foldable operations that work with applicative effects.

trait TraverseLaws[F[_]] extends FunctorLaws[F] with FoldableLaws[F] {
  implicit override def F: Traverse[F]
}

trait FoldableLaws[F[_]] {
  implicit def F: Foldable[F]
}

Traversal Laws

Bifunctor Laws

Laws for bifunctors and related binary type constructors.

trait BifunctorLaws[F[_, _]] {
  implicit def F: Bifunctor[F]
  def bifunctorIdentity[A, B](fab: F[A, B]): IsEq[F[A, B]]
  def bifunctorComposition[A, B, C, D](fab: F[A, B], f: A => C, g: B => D, f2: C => C, g2: D => D): IsEq[F[C, D]]
}

Bifunctor Laws

Comonad Laws

Laws for comonads and coflatMap operations.

trait ComonadLaws[F[_]] extends CoflatMapLaws[F] {
  implicit override def F: Comonad[F]
}

trait CoflatMapLaws[F[_]] extends FunctorLaws[F] {
  implicit override def F: CoflatMap[F]
}

Comonad Laws

Category Theory Laws

Laws for categories, arrows, and compositional structures.

trait CategoryLaws[F[_, _]] extends ComposeLaws[F] {
  implicit override def F: Category[F]
}

trait ArrowLaws[F[_, _]] extends CategoryLaws[F] with StrongLaws[F] {
  implicit override def F: Arrow[F]
}

Category Theory Laws

Commutative Laws

Laws for commutative versions of applicative functors and monads.

trait CommutativeMonadLaws[F[_]] extends CommutativeApplicativeLaws[F] with CommutativeFlatMapLaws[F] with MonadLaws[F]

trait CommutativeApplicativeLaws[F[_]] extends CommutativeApplyLaws[F] with ApplicativeLaws[F]

Commutative Laws

Error Handling Laws

Laws for error handling with ApplicativeError and MonadError.

trait ApplicativeErrorLaws[F[_], E] extends ApplicativeLaws[F] {
  implicit override def F: ApplicativeError[F, E]
}

trait MonadErrorLaws[F[_], E] extends ApplicativeErrorLaws[F, E] with MonadLaws[F] {
  implicit override def F: MonadError[F, E]
}

Error Handling Laws

Parallel and Align Laws

Laws for parallel operations and alignment of functors.

trait ParallelLaws[M[_], F[_]] {
  def parallel: Parallel.Aux[M, F]
}

trait AlignLaws[F[_]] extends FunctorLaws[F] {
  implicit override def F: Align[F]
  def alignAssociativity[A, B, C](fa: F[A], fb: F[B], fc: F[C]): IsEq[F[Ior[Ior[A, B], C]]]
}

Parallel and Align Laws

Testing Utilities

Utility classes and objects for property-based testing and law verification.

trait ExhaustiveCheck[A] {
  def allValues: List[A]
}

case class MiniInt(toInt: Int) extends AnyVal {
  def +(other: MiniInt): MiniInt
  def *(other: MiniInt): MiniInt
}

Testing Utilities

Key Types

// Core law verification type
type IsEq[A] = cats.kernel.laws.IsEq[A]

// Implicit class for creating IsEq instances
implicit final class IsEqArrow[A](private val lhs: A) extends AnyVal {
  def <->(rhs: A): IsEq[A]
}

// ScalaCheck rule sets for organized testing
trait RuleSet {
  def name: String
  def bases: Seq[(String, RuleSet)]
  def props: Seq[(String, Prop)]
}