memeid: A Scala repository from 47 Degrees Open Source

memeid is a JVM library for generating RFC-compliant Universal Unique Identifiers (UUIDs).

A universally unique identifier (UUID) is a 128-bit number used to identify information in computer systems.

When generated according to the standard methods, UUIDs are for practical purposes unique. Their uniqueness does not depend on a central registration authority or coordination between the parties generating them, unlike most other numbering schemes. -- Wikipedia article on UUIDs

Rationale
Install
- Java
  - Using maven
  - Using gradle
- Scala
Usage
- Scala
Benchmarking
References

Rationale

The UUID type that ships with the JVM java.util.UUID has a number of problems, namely:

A bug in the comparison function that will never be fixed
Only provides UUID generation for random (V4) and non-namespaced pseudo-V3 UUIDs

This library aims to solve the aforementioned issues and provide an RFC-compliant UUID type with coherent comparison, a rich API to get its different fields and constructors for the UUID variants.

Install

Java

Using maven

<dependency>
    <groupId>com.47deg</groupId>
    <artifactId>memeid</artifactId>
    <version>0.8.0</version>
</dependency>

Using gradle

compile group: 'com.47deg', name: 'memeid', version: '0.8.0'

Scala

Add this to your build.sbt file:

libraryDependencies += "com.47deg" %% "memeid4s" % "0.8.0"

Usage

Scala

UUID construction

Time-based (v1)

The time-based (V1) variant of UUIDs is the fastest to generate. It uses a monotonic clock and node information to generate UUIDs.

import memeid4s.UUID

UUID.V1.next

Random (v4)

The cryptographically random variant, equivalent to java.util.UUID/randomUUID.

UUID.V4.random

Namespaced (v3, v5)

Namespaced UUIDs are generated from a UUID (namespace) and a hashed value (name), V3 uses MD5 and V5 uses SHA1 hash.

val namespace = UUID.V1.next

We can now create UUIDs with the namespace and an arbitrary value as the name. It automatically works with Strings and UUIDs:

UUID.V3(namespace, "my-secret-code")

If you want to hash a custom type, you must provide an implicit memeid4s.digest.Digestible instance.

import memeid4s.digest.Digestible

case class User(firstName: String, lastName: String)

implicit val digestibleUser: Digestible[User] =
  (u: User) => u.firstName.getBytes ++ u.lastName.getBytes

The implicit instance is used to convert your type into a byte array for hashing:

UUID.V3(namespace, User("Federico", "García Lorca"))

Semi-sequential, random (SQUUID)

SQUUIDs are a non-standard variaton of V4 UUIDs that are semi-sequential. They incorporate a time-component in their 32 most significant bits to generate UUIDs that don't fragment DB indexes.

UUID.V4.squuid

Java interoperability

memeid provides conversion method between UUID and java.util.UUID through:

val j = java.util.UUID.fromString("a5fa7934-501c-46eb-9ea7-16de3086e6d8")

val u = memeid.UUID.fromString("8b4d1529-5fd0-4a91-8f4f-ceee10d1c060")

UUID.fromUUID(j)
// res5: UUID = a5fa7934-501c-46eb-9ea7-16de3086e6d8

u.asJava
// res6: java.util.UUID = 8b4d1529-5fd0-4a91-8f4f-ceee10d1c060

Literal syntax

memeid provides literal syntax with compile-time verification for UUIDs with the uuid interpolator. To use it, add this to your build.sbt:

libraryDependencies += "com.47deg" %% "memeid4s-literal" % "0.8.0"

We can now create UUIDs with literal syntax by importing memeid.literal._

import memeid4s.literal._

uuid"cb096727-6a82-4abd-bc79-fc92be8c5d88"
// res7: UUID = cb096727-6a82-4abd-bc79-fc92be8c5d88

Invalid UUID literals will fail at compile time:

uuid"not-a-uuid"
// error: invalid UUID: not-a-uuid
// uuid"not-a-uuid"
// ^^^^^^^^^^^^^^^^

Integrations

memeid provides several modules which integrate with popular third-party libraries. If you see something missing don't hesitate to open an issue or send a patch.

Doobie

The Doobie integration allows you to use the UUID type mapped to your database's UUID type.

libraryDependencies += "com.47deg" %% "memeid4s-doobie" % "0.8.0"

To have the UUID mappings available in scope you can import memeid.doobie.implicits.

import memeid4s.doobie.implicits._

def select(uuid: UUID): Query0[UUID] =
  sql"""SELECT id from test where id = $uuid""".query[UUID]

def insert(uuid: UUID): Update0 =
  sql"""insert into test (id) values ($uuid)""".update

val example = uuid"58d61328-1b08-1171-1ee7-1283ed639e77"

{
  for {
    _ <- insert(example).run.transact(transactor)
    u <- select(example).unique.transact(transactor)
  } yield u
}.unsafeRunSync()
// res10: UUID = 58d61328-1b08-1171-1ee7-1283ed639e77

Circe

libraryDependencies += "com.47deg" %% "memeid4s-circe" % "0.8.0"

You can import memeid.circe.implicits to have the Encoder and Decoder instances for UUID in scope.

import io.circe.Json

import io.circe.Encoder
import io.circe.Decoder

import memeid4s.circe.implicits._

val uuid = uuid"58d61328-1b08-1171-1ee7-1283ed639e77"

val json = Json.fromString(uuid.toString)

Encoder[UUID].apply(uuid)
// res11: Json = JString(value = "58d61328-1b08-1171-1ee7-1283ed639e77")
Decoder[UUID].decodeJson(json)
// res12: Decoder.Result[UUID] = Right(
//   value = 58d61328-1b08-1171-1ee7-1283ed639e77
// )

Http4s

libraryDependencies += "com.47deg" %% "memeid4s-http4s" % "0.8.0"

Path parameters

Using UUID companion object we can extract UUIDs from path parameters in URLs:

import cats.effect._

import org.http4s._
import org.http4s.dsl.io._

HttpRoutes.of[IO] { case GET -> Root / "user" / UUID(uuid) =>
  Ok(s"Hello, $uuid!")
}

Query parameters

The http4s integrations provides implicit instances for QueryParamDecoder[UUID] and QueryParamEncoder[UUID], which you can use to derive matchers for query parameters or send UUID in request query parameters.

import cats.effect._

import org.http4s._
import org.http4s.dsl.io._

import memeid4s.http4s.implicits._

object UUIDParamDecoder extends QueryParamDecoderMatcher[UUID]("uuid")

HttpRoutes.of[IO] { case GET -> Root / "user" :? UUIDParamDecoder(uuid) =>
  Ok(s"Hello, $uuid!")
}

Tapir

libraryDependencies += "com.47deg" %% "memeid4s-tapir" % "0.8.0"

The Tapir integration provides implicit instances for Codec[UUID] and Schema[UUID], which allow using UUID as type for query/path params or headers in endpoints. As well as enriching documentation when a UUID field is used.

import memeid4s.tapir.implicits._

import sttp.tapir._

endpoint.get.in("hello" / path[UUID])

FUUID

libraryDependencies += "com.47deg" %% "memeid4s-fuuid" % "0.8.0"

The FUUID integration provides both semi (via extension methods) and auto conversions between memeid's UUID type and FUUID.

import memeid4s.UUID

import io.chrisdavenport.fuuid.FUUID
import memeid4s.fuuid.syntax._

val fuuid: FUUID = UUID.V4.random.toFUUID

val uuid: UUID = fuuid.toUUID

import memeid4s.UUID

import io.chrisdavenport.fuuid.FUUID
import memeid4s.fuuid.auto._

def usingFUUID(fuuid: FUUID) = fuuid

def usingUUID(uuid: UUID) = uuid

val uuid: UUID = UUID.V4.random

val fuuid: FUUID = FUUID.fromUUID(java.util.UUID.randomUUID)

usingFUUID(uuid)
usingUUID(fuuid)

Cats & Cats-effect

libraryDependencies += "com.47deg" %% "memeid4s-cats" % "0.8.0"

The cats integration provides typeclass implementation for UUID, as well as effectful constructors for UUIDs for integration with programs that use cats-effect.

Typeclasses

import cats._

import memeid4s.cats.implicits._
import cats.effect.IO

Order[UUID]
Hash[UUID]
Eq[UUID]
Show[UUID]

Constructors

UUID.random[IO]

val namespace = UUID.V4.random

UUID.v3[IO, String](namespace, "my-secret-code")
UUID.v5[IO, String](namespace, "my-secret-code")

Scalacheck

libraryDependencies += "com.47deg" %% "memeid4s-scalacheck" % "0.8.0"

The scalacheck integration provides Arbitrary instances for the UUID, as well as for the different version classes.

import org.scalacheck.Arbitrary.arbitrary

import memeid4s.scalacheck.arbitrary.instances._

arbitrary[UUID]
arbitrary[UUID.V1]
arbitrary[UUID.V2]
arbitrary[UUID.V3]
arbitrary[UUID.V4]
arbitrary[UUID.V5]

Benchmarking

sbt-jmh is used for executing the benchmarking tests.

There are 2 kind of benchmarking:

runAvgtime: Measures the average time it takes for the benchmark method to execute (a single execution). Generates the master.avgtime.csv file in the bench folder.
runThroughput: Measures the number of operations per second, meaning the number of times per second your benchmark method could be executed. Generates the master.throughput.csv file in the bench folder.

References

RFC 4122 - A Universally Unique Identifier
JVM UUID type
clj-uuid Clojure implementation

47degrees/memeid

Rationale

Install

Java

Using maven

Using gradle

Scala

Usage

Scala

UUID construction

Time-based (v1)

Random (v4)

Namespaced (v3, v5)

Semi-sequential, random (SQUUID)

Java interoperability

Literal syntax

Integrations

Doobie

Circe

Http4s

Path parameters

Query parameters

Tapir

FUUID

Cats & Cats-effect

Typeclasses

Constructors

Scalacheck

Benchmarking

References