ant8e / uuid4cats-effect   0.5.0

Apache License 2.0 GitHub

UUID V1, V4, V6, V7 & TypeID generation with cats-effect

Scala versions: 3.x 2.13
Scala.js versions: 1.x

Maven Central javadoc Code of Conduct codecov

uuid4cats-effect - UUID and TypeID Generation for cats effect

Although cats-effect has some support for generating UUIDs, it is limited to the UUIDv4 pseudo-random type.

This library add support for the following types:

time-based sortable random
UUID v1
gregorian calendar
UUID v4
UUID v6
gregorian calendar
UUID v7
unix epoch

Implementation based on this UUID RFC Draft

In addition to UUID, there is also support for TypeIDs. TypeIDs are a modern, type-safe extension of UUIDv7. This implementation is compatible with the 0.3.0 version of the specification

Quickstart

To use uuid4cats-effect in an existing SBT project with Scala 2.13 or a later version, add the following dependency to your build.sbt:

libraryDependencies += "tech.ant8e" %% "uuid4cats-effect" % "<version>"

uuid4cats-effect is published for Scala 2.13, and 3 on JVM and JS.

Example

import cats.effect.IO
import cats.effect.unsafe.implicits.global
import tech.ant8e.uuid4cats.UUIDv6
import tech.ant8e.uuid4cats.UUIDUtil
import tech.ant8e.uuid4cats.TypeID

val ids = for {
  generator <- UUIDv6.generator[IO]
  typeIDGenerator <- TypeID.generator[IO]
  uuid1 <- generator.uuid
  uuid2 <- generator.uuid
  typeid <- typeIDGenerator.typeid("myprefix")
  ts = UUIDUtil.extractTimestamp(uuid1)
} yield (uuid1, uuid2, typeid.value, ts)

ids.unsafeRunSync()


val ids: cats.effect.IO[(java.util.UUID, java.util.UUID, String)] = IO(...)
val res1: (java.util.UUID, java.util.UUID, String) = (1ee22392-7669-6aa0-8000-ca7de6e5d540,1ee22392-766c-61b0-8000-422a97a9dbaa,myprefix_01h5a2ccabe0080m1hrkj0p0qp, Some(2024-04-28T11:10:44.501Z))

Uniqueness of generated time-based UUIDs is guaranteed when using the same generator. Collisions across generators are theoretically possible although unlikely.