Cats Helper

ClockHelper

import com.evolutiongaming.catshelper.ClockHelper._

val clock = Clock.const[Id](nanos = 1000, millis = 2)

clock.millis // 2
clock.nanos // 1000
clock.micros // 1
clock.instant // Instant.ofEpochMilli(2)

MeasureDuration

Provides a way to measure duration of a computation in a pure way.

Example:

import com.evolutiongaming.catshelper.MeasureDuration

for {
  duration <- MeasureDuration[IO].start
  _        <- doSomething
  duration <- duration
} yield duration

Syntax extensions are also available, allowing to measure duration of a computation and execute an effect with it:

import com.evolutiongaming.catshelper.syntax.measureDuration._

for {
  int1 <- IO.pure(1).measured(elapsed => IO.println(s"elapsed: $elapsed"))
  int2 <- IO.pure(1).measuredCase(
    successF = elapsed => IO.println(s"Succeeded: $elapsed"),
    failureF = elapsed => IO.println(s"Failed: $elapsed")
  )
} yield int1 + int2

SerialRef

Like Ref but allows A => F[A] rather than A => A
Ensures that updates are run serially

import com.evolutiongaming.catshelper.SerialRef

for {
  ref <- SerialRef.of[IO, Int](0)
  _   <- ref.update(a => (a + 1).pure[IO])
} yield {}

LazyVal

Functional alternative to lazy keyword in Scala

trait LazyVal[F[_], A] {

  def get: F[A]

  def getLoaded: F[Option[A]]
}

ToFuture & FromFuture

trait ToFuture[F[_]] {
  def apply[A](fa: F[A]): Future[A]
}

trait FromFuture[F[_]] {
  def apply[A](future: => Future[A]): F[A]
}

ToTry & FromTry

trait ToTry[F[_]] {

  def apply[A](fa: F[A]): Try[A]
}

trait FromTry[F[_]] {

  def apply[A](fa: Try[A]): F[A]
}

Log

trait Log[F[_]] {

  def debug(msg: => String): F[Unit]

  def info(msg: => String): F[Unit]

  def warn(msg: => String): F[Unit]

  def warn(msg: => String, cause: Throwable): F[Unit]

  def error(msg: => String): F[Unit]

  def error(msg: => String, cause: Throwable): F[Unit]
}

Runtime

trait Runtime[F[_]] {

  def availableCores: F[Int]

  def freeMemory: F[Long]

  def totalMemory: F[Long]

  def maxMemory: F[Long]

  def gc: F[Unit]
}

ThreadLocalRef

trait ThreadLocalRef[F[_], A] {

  def get: F[A]

  def set(a: A): F[Unit]

  def update(f: A => A): F[Unit]

  def modify[B](f: A => (A, B)): F[B]
}

ResourceFenced

This is useful to ensure release called at most once, in cases when "unsafe" api like Resource.allocated being used

val resource: Resource[F, A] = ???
resource.fenced

ReadWriteRef

A mutable reference to A value with read-write lock semantics.

FeatureToggled

Manages a given Resource[F, A] providing access to it only when a feature-toggle is on.

val serviceResource: Resource[F, AService] = ???
val flag: F[Boolean] = ???

val ftService: Resource[F, Resource[F, Option[AService]]] = FeatureToggled
  .polling(
    serviceResource,
    flag,
    pollInterval = 10.seconds,
    gracePeriod = 30.seconds,
  )

ftService.use { access =>
  access.use {
    case Some(service) => service.doStuff(…)
    case None          => F.unit
  }
}

Logback module

Separate module

The logback module lives in a separate `cats-helper-logback' module to avoid dependency on a logback in case the user chooses a different logging backend. This is important to avoid the problem of multiple bindings when mapping the logging framework with SLF4J.

LogOfFromLogback

Motivation

Direct logback usage required to overcome limitations of SLF4J MDC API. SLF4J MDC API heavily rely on [[ThreadLocal]], example: ch.qos.logback.classic.util.LogbackMDCAdapter Logback' [[LoggingEvent]] allow setting MDC directly as Java map that should have performance benefits compared with SLF4J/Logback implementation.

CAUTION!

Please be aware that using other version of logback (than used in cats-helper-logback) might bring '''RUNTIME ERRORS''' or '''MISSING LOGS''' in case of binary incompatibility between them. Suggested approach is in using exactly same logback version as used in cats-helper-logback (among all others available through transitive dependencies)

SLF4J compatibility

In some cases it may be necessary to allocate the logback instance manually as well as using the SLF4J API in the end user code. However, if multiple LoggerContexts are instantiated at the same time, this could lead to unexpected behaviour, such as the RollingFileAppender writing to multiple files instead of one. To cover such cases, the internal implementation of LogOfFromLogback uses the SLF4J API to instantiate the logback context, so that later use of the SLF4J API will pick up the same context instance created by LogOfFromLogback.

PureTest

This helper lives in a separate cats-helper-testkit module. It is makes testing F[_]-based code easier.

NOTE: cats-helper-testkit is an experimental module and may break SemVer guarantees from time to time. However we will do our best to avoid unnecessary breakages.

"what time is it now?" in PureTest[IO].of { env =>
  import env._
  for {
    _ <- IO.sleep(1.hour)
    _ <- testRuntime.getTimeSinceStart.map(_ shouldBe 1.hour)
  } yield ()
}

Setup

addSbtPlugin("com.evolution" % "sbt-artifactory-plugin" % "0.0.2")

libraryDependencies += "com.evolutiongaming" %% "cats-helper" % "2.2.3"