https://github.com/evolution-gaming/cats-helper
Helpers for cats & cats-effect
https://github.com/evolution-gaming/cats-helper
cats cats-effect scala tagless-final
Last synced: 8 months ago
JSON representation
Helpers for cats & cats-effect
- Host: GitHub
- URL: https://github.com/evolution-gaming/cats-helper
- Owner: evolution-gaming
- License: mit
- Created: 2019-03-06T20:57:03.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-08-12T13:52:48.000Z (almost 2 years ago)
- Last Synced: 2024-08-13T11:03:39.814Z (almost 2 years ago)
- Topics: cats, cats-effect, scala, tagless-final
- Language: Scala
- Size: 488 KB
- Stars: 49
- Watchers: 11
- Forks: 17
- Open Issues: 41
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Cats Helper
[](https://github.com/evolution-gaming/cats-helper/actions?query=workflow%3ACI)
[](https://coveralls.io/r/evolution-gaming/cats-helper)
[](https://app.codacy.com/gh/evolution-gaming/cats-helper/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[](https://evolution.jfrog.io/artifactory/api/search/latestVersion?g=com.evolutiongaming&a=cats-helper_2.13&repos=public)
[](https://opensource.org/licenses/MIT)
## ClockHelper
```scala
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:
```scala
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:
```scala
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`](https://typelevel.org/cats-effect/concurrency/ref.html) but allows `A => F[A]` rather than `A => A`
Ensures that updates are run serially
```scala
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
```scala
trait LazyVal[F[_], A] {
def get: F[A]
def getLoaded: F[Option[A]]
}
```
## ToFuture & FromFuture
```scala
trait ToFuture[F[_]] {
def apply[A](fa: F[A]): Future[A]
}
trait FromFuture[F[_]] {
def apply[A](future: => Future[A]): F[A]
}
```
## ToTry & FromTry
```scala
trait ToTry[F[_]] {
def apply[A](fa: F[A]): Try[A]
}
trait FromTry[F[_]] {
def apply[A](fa: Try[A]): F[A]
}
```
## Log
```scala
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
```scala
trait Runtime[F[_]] {
def availableCores: F[Int]
def freeMemory: F[Long]
def totalMemory: F[Long]
def maxMemory: F[Long]
def gc: F[Unit]
}
```
## ThreadLocalRef
```scala
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
```scala
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.
```scala
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.
```scala
"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
```scala
addSbtPlugin("com.evolution" % "sbt-artifactory-plugin" % "0.0.2")
libraryDependencies += "com.evolutiongaming" %% "cats-helper" % "2.2.3"
```