add annotation-based prefix customization

Author: Adrian Tosca

README.md

@@ -1,6 +1,6 @@
 # typeid-kotlin
 ![Build Status](https://github.com/aleris/typeid-kotlin/actions/workflows/build-on-push.yml/badge.svg)
-![Current Version](https://img.shields.io/badge/Version-0.0.10-blue)
+![Current Version](https://img.shields.io/badge/Version-0.0.11-blue)
 
 
 ## A Kotlin implementation of [TypeID](https://github.com/jetpack-io/typeid).
@@ -25,14 +25,14 @@ To use with Maven:
 <dependency>
     <groupId>earth.adi</groupId>
     <artifactId>typeid-kotlin</artifactId>
-    <version>0.0.10</version>
+    <version>0.0.11</version>
 </dependency>
 ```
 
 To use via Gradle:
 
 ```kotlin
-implementation("earth.adi:typeid-kotlin:0.0.10")
+implementation("earth.adi:typeid-kotlin:0.0.11")
 ```
 
 
@@ -208,6 +208,29 @@ val typeId = typeId().withCustomPrefix(TypedPrefix<Organization>("org"))
 println(typeId.randomId<Organization>()) // prints something like org_01h455vb4pex5vsknk084sn02q
 ```
 
+Another possibility is to add `TypedPrefix` to the entity instance:
+
+```kotlin
+@TypeIdPrefix("cust")
+data class Customer(override val id: CustomerId)
+```
+
+This can also be useful when you want a different entity interface in a different module. For example:  
+
+```kotlin
+@TypeIdPrefix("customer")
+interface CustomerIdentifiable {
+  val id: CustomerId
+}
+
+typealias CustomerId = Id<out CustomerIdentifiable>
+
+data class Customer(override val id: CustomerId) : CustomerIdentifiable
+```
+
+If the `@TypeIdPrefix` is present TypeId will use that. 
+Note that the prefixes registered trough the `TypeId` instance will take precedence over the ones defined in the entity.
+
 
 ### Customizing the UUID generator
 

build.gradle.kts

@@ -15,7 +15,7 @@ plugins {
 
 group = "earth.adi"
 
-version = "0.0.10"
+version = "0.0.11"
 
 repositories { mavenCentral() }
 

src/main/kotlin/earth/adi/typeid/annotations/TypeIdPrefix.kt

@@ -0,0 +1,6 @@
+package earth.adi.typeid.annotations
+
+@Target(AnnotationTarget.CLASS)
+@Retention(AnnotationRetention.RUNTIME)
+@MustBeDocumented
+annotation class TypeIdPrefix(val value: String)

src/main/kotlin/earth/adi/typeid/codec/Factory.kt

@@ -5,6 +5,7 @@ import earth.adi.typeid.Id
 import earth.adi.typeid.RawId
 import earth.adi.typeid.TypedPrefix
 import earth.adi.typeid.Validated
+import earth.adi.typeid.annotations.TypeIdPrefix
 import java.util.*
 
 /**
@@ -181,6 +182,13 @@ class Factory {
   }
 
   private fun <TEntity> defaultPrefix(entityType: Class<out TEntity>): TypedPrefix<out TEntity> {
+    entityType.annotations
+        .find { it is TypeIdPrefix }
+        ?.let {
+          val typeIdPrefix = (it as TypeIdPrefix).value
+          Codec.requireValidPrefix(typeIdPrefix)
+          return TypedPrefix(typeIdPrefix)
+        }
     return TypedPrefix(entityType.simpleName.lowercase())
   }
 }

src/test/kotlin/earth/adi/typeid/TypeIdTest.kt

@@ -1,5 +1,9 @@
 package earth.adi.typeid
 
+import earth.adi.typeid.testentities.CustomerIdentifiable
+import earth.adi.typeid.testentities.Organization
+import earth.adi.typeid.testentities.User
+import earth.adi.typeid.testentities.UserRepository
 import java.util.*
 import org.assertj.core.api.Assertions.assertThat
 import org.assertj.core.api.Assertions.assertThatThrownBy
@@ -129,6 +133,12 @@ class TypeIdTest {
     assertThat(organizationId.toString()).startsWith("org_")
   }
 
+  @Test
+  fun `randomId with prefix customization in annotation`() {
+    val customerId = typeId.randomId<CustomerIdentifiable>() // customer_01hy0sk45qfmdsdme1j703yjet
+    assertThat(customerId.toString()).startsWith("customer_")
+  }
+
   @Test
   fun `tryParse valid`() {
     val organizationId = typeId.randomId<Organization>()

src/test/kotlin/earth/adi/typeid/ValidatedTest.kt

@@ -1,5 +1,7 @@
 package earth.adi.typeid
 
+import earth.adi.typeid.testentities.User
+import earth.adi.typeid.testentities.UserId
 import java.util.concurrent.atomic.AtomicBoolean
 import org.assertj.core.api.Assertions.assertThat
 import org.junit.jupiter.api.Test

src/test/kotlin/earth/adi/typeid/jackson/JacksonJsonTest.kt

@@ -6,6 +6,7 @@ import com.fasterxml.jackson.databind.PropertyName
 import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
 import com.fasterxml.jackson.module.kotlin.readValue
 import earth.adi.typeid.*
+import earth.adi.typeid.testentities.*
 import java.io.ByteArrayOutputStream
 import org.assertj.core.api.Assertions.assertThat
 import org.junit.jupiter.api.Test
@@ -30,14 +31,15 @@ class JacksonJsonTest {
 
   private val objectMapper = jacksonObjectMapper().registerModule(typeId.jacksonModule())
 
-  data class JsonUserAndOrganization(
+  data class EntitiesWithIds(
       val user: User,
       val organization: Organization,
+      val customer: Customer,
   )
 
   @Test
   fun `deserialize from json`() {
-    val json = objectMapper.readValue<JsonUserAndOrganization>(JSON_USER_AND_ORGANIZATION)
+    val json = objectMapper.readValue<EntitiesWithIds>(JSON_ENTITIES_WITH_IDS)
     assertThat(json.user.id).isEqualTo(typeId.parse<User>("user_01hy0d96sgfx0rh975kqkspchh"))
     assertThat(json.organization.id)
         .isEqualTo(typeId.parse<Organization>("org_01hy0sk45qfmdsdme1j703yjet"))
@@ -46,17 +48,19 @@ class JacksonJsonTest {
   @Test
   fun `serialize to json`() {
     val json =
-        JsonUserAndOrganization(
+        EntitiesWithIds(
             User(typeId.parse<User>("user_01hy0d96sgfx0rh975kqkspchh")),
             Organization(typeId.parse<Organization>("org_01hy0sk45qfmdsdme1j703yjet")),
+            Customer(typeId.parse<CustomerIdentifiable>("customer_01hyb7c8a3eyws8s8d037qfr6b")),
         )
     val writtenJson = objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(json)
-    assertThat(writtenJson).isEqualTo(JSON_USER_AND_ORGANIZATION)
+    assertThat(writtenJson).isEqualTo(JSON_ENTITIES_WITH_IDS)
   }
 
   data class IdsOnly(
       @JsonProperty("user_id") val userId: UserId,
       @JsonProperty("org_id") val organizationId: OrganizationId,
+      @JsonProperty("customer_id") val customerId: CustomerId,
   )
 
   @Test
@@ -65,6 +69,8 @@ class JacksonJsonTest {
     assertThat(json.userId).isEqualTo(typeId.parse<User>("user_01hy0d96sgfx0rh975kqkspchh"))
     assertThat(json.organizationId)
         .isEqualTo(typeId.parse<Organization>("org_01hy0sk45qfmdsdme1j703yjet"))
+    assertThat(json.customerId)
+        .isEqualTo(typeId.parse<CustomerIdentifiable>("customer_01hyb7c8a3eyws8s8d037qfr6b"))
   }
 
   @Test
@@ -73,6 +79,7 @@ class JacksonJsonTest {
         IdsOnly(
             typeId.parse<User>("user_01hy0d96sgfx0rh975kqkspchh"),
             typeId.parse<Organization>("org_01hy0sk45qfmdsdme1j703yjet"),
+            typeId.parse<CustomerIdentifiable>("customer_01hyb7c8a3eyws8s8d037qfr6b"),
         )
     val writtenJson = objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(json)
     assertThat(writtenJson).isEqualTo(JSON_IDS_ONLY)
@@ -81,13 +88,15 @@ class JacksonJsonTest {
   data class RawIds(
       @JsonProperty("user_id") val userId: RawId,
       @JsonProperty("org_id") val organizationId: RawId,
+      @JsonProperty("customer_id") val customerId: RawId,
   )
 
   @Test
   fun `deserialize raw ids from json`() {
     val json = objectMapper.readValue<RawIds>(JSON_IDS_ONLY)
     assertThat(json.userId).isEqualTo(typeId.parse("user_01hy0d96sgfx0rh975kqkspchh"))
     assertThat(json.organizationId).isEqualTo(typeId.parse("org_01hy0sk45qfmdsdme1j703yjet"))
+    assertThat(json.customerId).isEqualTo(typeId.parse("customer_01hyb7c8a3eyws8s8d037qfr6b"))
   }
 
   @Test
@@ -96,6 +105,7 @@ class JacksonJsonTest {
         RawIds(
             typeId.parse("user_01hy0d96sgfx0rh975kqkspchh"),
             typeId.parse("org_01hy0sk45qfmdsdme1j703yjet"),
+            typeId.parse("customer_01hyb7c8a3eyws8s8d037qfr6b"),
         )
     val writtenJson = objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(json)
     assertThat(writtenJson).isEqualTo(JSON_IDS_ONLY)
@@ -150,14 +160,17 @@ class JacksonJsonTest {
       """
             .trimIndent()
 
-    private val JSON_USER_AND_ORGANIZATION =
+    private val JSON_ENTITIES_WITH_IDS =
         """
       {
         "user" : {
           "id" : "user_01hy0d96sgfx0rh975kqkspchh"
         },
         "organization" : {
           "id" : "org_01hy0sk45qfmdsdme1j703yjet"
+        },
+        "customer" : {
+          "id" : "customer_01hyb7c8a3eyws8s8d037qfr6b"
         }
       }
       """
@@ -167,7 +180,8 @@ class JacksonJsonTest {
         """
       {
         "user_id" : "user_01hy0d96sgfx0rh975kqkspchh",
-        "org_id" : "org_01hy0sk45qfmdsdme1j703yjet"
+        "org_id" : "org_01hy0sk45qfmdsdme1j703yjet",
+        "customer_id" : "customer_01hyb7c8a3eyws8s8d037qfr6b"
       }
       """
             .trimIndent()

src/test/kotlin/earth/adi/typeid/testentities/CustomerId.kt

@@ -0,0 +1,13 @@
+package earth.adi.typeid.testentities
+
+import earth.adi.typeid.Id
+import earth.adi.typeid.annotations.TypeIdPrefix
+
+@TypeIdPrefix("customer")
+interface CustomerIdentifiable {
+  val id: CustomerId
+}
+
+typealias CustomerId = Id<out CustomerIdentifiable>
+
+data class Customer(override val id: CustomerId) : CustomerIdentifiable

src/test/kotlin/earth/adi/typeid/OrganizationId.kt renamed to src/test/kotlin/earth/adi/typeid/testentities/OrganizationId.kt

@@ -1,4 +1,6 @@
-package earth.adi.typeid
+package earth.adi.typeid.testentities
+
+import earth.adi.typeid.Id
 
 data class Organization(val id: OrganizationId)
 

src/test/kotlin/earth/adi/typeid/UserId.kt renamed to src/test/kotlin/earth/adi/typeid/testentities/UserId.kt

@@ -1,4 +1,6 @@
-package earth.adi.typeid
+package earth.adi.typeid.testentities
+
+import earth.adi.typeid.Id
 
 data class User(val id: UserId)
 

src/test/kotlin/earth/adi/typeid/UserRepository.kt renamed to src/test/kotlin/earth/adi/typeid/testentities/UserRepository.kt

@@ -1,4 +1,4 @@
-package earth.adi.typeid
+package earth.adi.typeid.testentities
 
 class UserRepository {
   fun get(id: UserId): User {