add isId convenience method

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.14-blue)
+![Current Version](https://img.shields.io/badge/Version-0.0.15-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.14</version>
+    <version>0.0.15</version>
 </dependency>
 ```
 
 To use via Gradle:
 
 ```kotlin
-implementation("earth.adi:typeid-kotlin:0.0.14")
+implementation("earth.adi:typeid-kotlin:0.0.15")
 ```
 
 
@@ -199,6 +199,19 @@ These approaches are much faster when the input is untrusted and can result in l
 (see [Benchmarks](#benchmarks)).
 
 
+### isId
+
+Check if a string is a valid id of the given type:
+
+```kotlin
+val isUserId = typeId.isId<UserId>("user_01h455vb4pex5vsknk084sn02q")
+```
+
+Is a convenience method that uses `parseToValidated` and returns a boolean.
+It can be used to check if a string is a valid id of an expected type 
+as it returns `false` if the id is valid but of a different type.
+
+
 ### Type safety
 
 At its base, a `typeid` is just a prefix followed by `_` and an encoded UUID 
@@ -293,7 +306,7 @@ for Java, Kotlin (kotlinx.serialization), and Jackson.
 
 #### Kotlin (kotlinx.serialization)
 
-Both [Id] and [RawId] have `@Serializable` and can be used with `kotlinx.serialization`.
+Both `Id` and `RawId` have `@Serializable` and can be used with `kotlinx.serialization`.
 You need to include the actual serialization dependency in your project.
 
 For example, with CBOR:

build.gradle.kts

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

src/main/kotlin/earth/adi/typeid/TypeId.kt

@@ -212,6 +212,30 @@ class TypeId(private var uuidGenerator: Supplier<UUID>) {
     return factory.parseToValidatedRaw(id)
   }
 
+  /**
+   * Checks if the given string is a valid [Id] for the inferred entity type.
+   *
+   * @param TEntity the inferred entity type
+   * @param id the string typeid representation of the [Id]
+   * @return `true` if the string is a valid [Id], `false` otherwise
+   */
+  inline fun <reified TEntity> isId(id: String): Boolean {
+    return isId(TEntity::class.java, id)
+  }
+
+  /**
+   * Checks if the given string is a valid [Id] for the given entity type.
+   *
+   * @param TEntity the entity type
+   * @param entityType the entity type class
+   * @param id the string typeid representation of the [Id]
+   * @return `true` if the string is a valid [Id], `false` otherwise
+   */
+  fun <TEntity> isId(entityType: Class<out TEntity>, id: String): Boolean {
+    val validated = parseToValidated(entityType, id)
+    return validated.map { true }.orElse(false)
+  }
+
   /**
    * Sets a custom UUID generator for generating new UUIDs. This replaces the default UUIDv7
    * generator.
@@ -448,6 +472,29 @@ class TypeId(private var uuidGenerator: Supplier<UUID>) {
       return DEFAULT.parseToValidated(entityType, id)
     }
 
+    /**
+     * Checks if the given string is a valid [Id] for the inferred entity type.
+     *
+     * @param TEntity the inferred entity type
+     * @param id the string typeid representation of the [Id]
+     * @return `true` if the string is a valid [Id], `false` otherwise
+     */
+    inline fun <reified TEntity> isId(id: String): Boolean {
+      return DEFAULT.isId<TEntity>(id)
+    }
+
+    /**
+     * Checks if the given string is a valid [Id] for the given entity type.
+     *
+     * @param TEntity the entity type
+     * @param entityType the entity type class
+     * @param id the string typeid representation of the [Id]
+     * @return `true` if the string is a valid [Id], `false` otherwise
+     */
+    fun <TEntity> isId(entityType: Class<out TEntity>, id: String): Boolean {
+      return DEFAULT.isId(entityType, id)
+    }
+
     /**
      * Parses an untyped [RawId] from a string and returns a [Validated] result. If the string is
      * valid a [Validated.Valid] result is returned, otherwise it returns an [Validated.Invalid].

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

@@ -98,6 +98,24 @@ class TypeIdTest {
             Validated.Invalid<User>("Id with empty prefix must not contain the separator '_'"))
   }
 
+  @Test
+  fun `default isId true`() {
+    val organizationId = TypeId.randomId<Organization>()
+    assertThat(TypeId.isId<Organization>(organizationId.toString())).isTrue()
+  }
+
+  @Test
+  fun `default isId true with entity type`() {
+    val organizationId = TypeId.randomId<Organization>()
+    assertThat(TypeId.isId(Organization::class.java, organizationId.toString())).isTrue()
+  }
+
+  @Test
+  fun `default isId false`() {
+    val organizationId = TypeId.randomId<Organization>()
+    assertThat(TypeId.isId<User>(organizationId.toString())).isFalse()
+  }
+
   @Test
   fun `default parseToValidated with entity type`() {
     val userId = TypeId.randomId<User>()
@@ -159,28 +177,37 @@ class TypeIdTest {
   }
 
   @Test
-  fun `tryParse valid`() {
+  fun `parse valid`() {
     val organizationId = typeId.randomId<Organization>()
     val parsedUserId = typeId.parse<Organization>(organizationId.toString())
     assertThat(parsedUserId).isEqualTo(organizationId)
   }
 
   @Test
-  fun `tryParse invalid`() {
+  fun `parse invalid`() {
     assertThatThrownBy { typeId.parse<Organization>("_") }
         .isInstanceOf(IllegalArgumentException::class.java)
   }
 
   @Test
-  fun `parse valid`() {
+  fun `parseToValidated valid`() {
     val organizationId = typeId.randomId<Organization>()
     val parsedOrganizationId = typeId.parseToValidated<Organization>(organizationId.toString())
     assertThat(parsedOrganizationId).isInstanceOf(Validated.Valid::class.java)
     assertThat(parsedOrganizationId).isEqualTo(Validated.Valid(organizationId))
   }
 
   @Test
-  fun `parse invalid`() {
+  fun `parseToValidated valid with entity type`() {
+    val organizationId = typeId.randomId<Organization>()
+    val parsedOrganizationId =
+        typeId.parseToValidated(Organization::class.java, organizationId.toString())
+    assertThat(parsedOrganizationId).isInstanceOf(Validated.Valid::class.java)
+    assertThat(parsedOrganizationId).isEqualTo(Validated.Valid(organizationId))
+  }
+
+  @Test
+  fun `parseToValidated invalid`() {
     val parsedOrganizationId = typeId.parseToValidated<Organization>("_")
     assertThat(parsedOrganizationId).isInstanceOf(Validated.Invalid::class.java)
     assertThat(parsedOrganizationId)
@@ -189,6 +216,35 @@ class TypeIdTest {
                 "Id with empty prefix must not contain the separator '_'"))
   }
 
+  @Test
+  fun `isId true`() {
+    val organizationId = typeId.randomId<Organization>()
+    assertThat(typeId.isId<Organization>(organizationId.toString())).isTrue()
+  }
+
+  @Test
+  fun `isId true with entity type`() {
+    val organizationId = typeId.randomId<Organization>()
+    assertThat(typeId.isId(Organization::class.java, organizationId.toString())).isTrue()
+  }
+
+  @Test
+  fun `isId false for other type`() {
+    val organizationId = typeId.randomId<Organization>()
+    assertThat(typeId.isId<User>(organizationId.toString())).isFalse()
+  }
+
+  @Test
+  fun `isId false for other type with entitytype`() {
+    val organizationId = typeId.randomId<Organization>()
+    assertThat(typeId.isId(User::class.java, organizationId.toString())).isFalse()
+  }
+
+  @Test
+  fun `isId false for invalid`() {
+    assertThat(typeId.isId<User>("user_not_valid_id")).isFalse()
+  }
+
   @Test
   fun `type safe parsing`() {
     val userId = typeId.randomId<User>()