This library is experimental, and it's future support is not guaranteed.

• Including
• Usage: from string, generating, hashing
• Serialization
• Using with ktor
• Migrating from java.util.UUID
• Using with Exposed
• Using with Gson
• Using with Jackson

kotlinx-uuid is a multiplatform (MPP) Kotlin library introducing support for UUID.

The main class UUID is serializable out of the box, so the library depends on kotlinx.serialization. If you don't need serialization, you don't need to apply the plugin.

Supported platforms are:

• JVM (Java 6+)
• JavaScript (including the new IR backend)
• Native:
  • MacOS X64, iOS ARM64 (untested)
  • Linux X64, ARM64 (untested)

*untested means that on that platform we didn't run any tests, just compiled.

repositories {
    maven("https://maven.pkg.github.com/cy6ergn0m/kotlinx-uuid")
}

val commonMain by getting {
    dependencies {
        implementation("org.jetbrains.kotlinx.experimental:kotlinx-uuid-core:0.1.0")
    }
}

In a regular (non-MPP) project you don't need the line with "commonMain", only the dependencies block.

val uuid = UUID("1b3e4567-e99b-13d3-a476-446657420000")
val guid = UUID("{1b3e4567-e99b-13d3-a476-446657420000}")

// using the default insecure kotlin.Random
val uuid = UUID.generateUUID()

// use secure random (just like java.util.UUID does)
val secure = UUID.generateUUID(SecureRandom().asKotlinRandom())

kotlinx-uuid provides the ability to generate uuids by hashing names (Only SHA-1 is supported at the moment).

val appNamespace = UUID("my-app-uuid")
val agentId = UUID.generateUUID(appNamespace, "agentId")

The other alternative is to generate UUID by hashing bytes (similar to java.util.UUID.nameUUIDFromBytes).

val uuid = UUID.generateUUID(bytes)

Note that unlike java.util.UUID, kotlinx's generateUUID doesn't support MD5, so the blind migration from Java to kotlinx-uuid may lead to changing UUIDs.

There are two serializers for UUID: the default one and the binary.

The default serializer does always serialize UUIDs as string primitives.

Json.encodeToString(uuid) == "\"1b3e4567-e99b-13d3-a476-446657420000\""

The additional serializer is useful for binary formats. Because they are not human-readable, and it's possible to reduce size.

val bytes = Protobuf.encodeToByteArray(BinarySerializer, uuid)

Include ktor-server-uuid artifact:

repositories {
    maven("https://maven.pkg.github.com/cy6ergn0m/kotlinx-uuid")
}

val jvmMain by getting {
    dependencies {
        implementation("org.jetbrains.kotlinx.experimental:ktor-server-uuid:0.1.0")
    }
}

Install converter:

install(DataConversion) {
    uuid()
}

Unfortunately, ktor doesn't provide (KTOR-1309) any way to plug converters automatically, so you need to configure it manually. Also, in some cases, like delegating to call parameters, it will not work and there is no workaround at the moment.

At the moment, DataConversion is going through the deprecation cycle due to server MPP migration. So there are two ConversionService interfaces. Using uuid() function is recommended without referreing to particular types.

Apply the following steps:

1. Remove all imports of import java.util.UUID
2. Add imports for UUID

import kotlinx.uuid.UUID
import kotlinx.uuid.*

3. Follow deprecations and apply all suggested replacements.

For example:

import java.util.UUID

fun f(id: String): UUID = UUID.fromString(id)

Becomes

import kotlinx.uuid.UUID

fun f(id: String) = UUID(id)

Note that unlike java.util.UUID.nameUUIDFromBytes, kotlinx's generateUUID doesn't support MD5, so the blind migration from Java to kotlinx-uuid may lead to changing UUIDs. This is why it is marked as error, so you need to think first, if you can simply replace it or not.

Exposed is an ORM framework for Kotlin. It has support for java.util.UUID, but to get kotlinx-uuid supported you need to include the corresponding dependency and use DSL functions:

repositories {
    maven("https://maven.pkg.github.com/cy6ergn0m/kotlinx-uuidd")
}

dependencies {
    implementation("org.jetbrains.kotlinx.experimental:exposed-uuid:0.1.0")
}

When declaring a table having UUID as Primary Key:

// SQL DSL
object MyTable : KotlinxUUIDTable() {
    // there is "id" property with the kotlinx-uuid type
}

// DAO API
class MyTableEntity(id: EntityID<UUID>): KotlinxUUIDEntity(id) {
    companion object: KotlinxUUIDEntityClass<MyTableEntity>(MyTable)
    
} 

To declare a regular column, use kotlinxUUID function:

object MyTable : Table() {
    val something = kotlinxUUID("SOME_COLUMN")
}

Unfortunately, there is a function called uuid in the base class, inside of the exposed core, this is why we can't overwrite/override it so it may lead to confusion. The function uuid only works with java.util.UUID:

object MyTable : Table() {
    val column1 = kotlinxUUID("C1") // kotlinx.uuid.UUID
    val column2 = uuid("C2") // java.util.UUID
}

To use [UUID] with Gson you need to register the serializer:

repositories {
    maven("https://maven.pkg.github.com/cy6ergn0m/kotlinx-uuid")
}

dependencies {
    implementation("org.jetbrains.kotlinx.experimental:gson-uuid:0.1.0")
}

val gson = GsonBuilder().registerUUID().create()

After that [UUID] will be serialized to JSON string primitives.

To use [UUID] with Jackson you need to register the module:

repositories {
    maven("https://maven.pkg.github.com/cy6ergn0m/kotlinx-uuid")
}

dependencies {
    implementation("org.jetbrains.kotlinx.experimental:jackson-module-uuid:0.1.0")
}

val jackson = ObjectMapper().uuid()

val json = jackson.writeValueAsString(
    UUID.generateUUID()
)

After that [UUID] will be serialized to JSON string primitives.

Having jackson-module-kotlin is recommended but not required.