feat: improve FriendlyId value object API

mariuszs · mariuszs · commit e7199a512491 · 2025-12-21T18:40:22.000+01:00
- Add parse() method accepting both UUID and FriendlyId string formats - Add friendlyId(UUID) factory method for static import usage - Add toUuid() method for symmetry with parse() - Add value() method returning the FriendlyId string - Update @SInCE annotation to 2.0 - Use static imports in deserializers - Update migration documentation
diff --git a/README.md b/README.md
@@ -367,17 +367,23 @@ import com.devskiller.friendly_id.type.FriendlyId;
 // Create from UUID
 FriendlyId id = FriendlyId.of(uuid);
 
-// Create from string
-FriendlyId id = FriendlyId.fromString("5wbwf6yUxVBcr48AMbz9cb");
+// Or use static import friendly method
+import static com.devskiller.friendly_id.type.FriendlyId.friendlyId;
+FriendlyId id = friendlyId(uuid);
+
+// Parse from string (accepts both FriendlyId and UUID formats)
+FriendlyId id = FriendlyId.parse("5wbwf6yUxVBcr48AMbz9cb");
+FriendlyId id = FriendlyId.parse("c3587ec5-0976-497f-8374-61e0c2ea3da5");
 
 // Create random
 FriendlyId id = FriendlyId.random();
 
 // Get UUID
-UUID uuid = id.uuid();
+UUID uuid = id.toUuid();
 
 // Get string representation
-String friendlyIdString = id.toString();
+String friendlyIdString = id.value();      // Returns FriendlyId string
+String friendlyIdString = id.toString();   // Same as value()
 ```
 
 The value object can be used in:
diff --git a/friendly-id-jackson-datatype/src/main/java/com/devskiller/friendly_id/jackson/FriendlyIdDeserializer.java b/friendly-id-jackson-datatype/src/main/java/com/devskiller/friendly_id/jackson/FriendlyIdDeserializer.java
@@ -9,10 +9,11 @@
 import tools.jackson.databind.ValueDeserializer;
 import tools.jackson.databind.deser.std.StdDeserializer;
 
-import com.devskiller.friendly_id.FriendlyId;
 import com.devskiller.friendly_id.FriendlyIdFormat;
 import com.devskiller.friendly_id.IdFormat;
 
+import static com.devskiller.friendly_id.type.FriendlyId.parse;
+
 public class FriendlyIdDeserializer extends StdDeserializer<UUID> {
 
 	private final boolean useFriendlyFormat;
@@ -32,36 +33,14 @@ public UUID deserialize(JsonParser parser, DeserializationContext ctxt) {
 		if (token == JsonToken.VALUE_STRING) {
 			var value = parser.getString().trim();
 			if (useFriendlyFormat) {
-				return parseAsUuidOrFriendlyId(value);
+				return parse(value).toUuid();
 			} else {
 				return UUID.fromString(value);
 			}
 		}
 		throw ctxt.weirdStringException(parser.getString(), UUID.class, "Expected UUID string value");
 	}
 
-	/**
-	 * Attempts to parse the value as a standard UUID first, then falls back to FriendlyId format.
-	 * This approach is more robust than heuristic-based detection.
-	 */
-	private UUID parseAsUuidOrFriendlyId(String value) {
-		if (isStandardUuidFormat(value)) {
-			return UUID.fromString(value);
-		}
-		return FriendlyId.toUuid(value);
-	}
-
-	/**
-	 * Checks if the string matches standard UUID format (36 chars with hyphens at positions 8, 13, 18, 23).
-	 */
-	private boolean isStandardUuidFormat(String value) {
-		return value.length() == 36
-				&& value.charAt(8) == '-'
-				&& value.charAt(13) == '-'
-				&& value.charAt(18) == '-'
-				&& value.charAt(23) == '-';
-	}
-
 	@Override
 	public ValueDeserializer<?> createContextual(DeserializationContext ctxt, BeanProperty property) {
 		if (property != null) {
diff --git a/friendly-id-jackson-datatype/src/main/java/com/devskiller/friendly_id/jackson/FriendlyIdValueDeserializer.java b/friendly-id-jackson-datatype/src/main/java/com/devskiller/friendly_id/jackson/FriendlyIdValueDeserializer.java
@@ -19,6 +19,6 @@ public FriendlyIdValueDeserializer() {
 	@Override
 	public FriendlyId deserialize(JsonParser p, DeserializationContext ctxt) {
 		String friendlyIdString = p.getString();
-		return FriendlyId.fromString(friendlyIdString);
+		return FriendlyId.parse(friendlyIdString);
 	}
 }
diff --git a/friendly-id-jackson2-datatype/src/main/java/com/devskiller/friendly_id/jackson2/FriendlyIdValueDeserializer.java b/friendly-id-jackson2-datatype/src/main/java/com/devskiller/friendly_id/jackson2/FriendlyIdValueDeserializer.java
@@ -17,6 +17,6 @@ public class FriendlyIdValueDeserializer extends JsonDeserializer<FriendlyId> {
 	@Override
 	public FriendlyId deserialize(JsonParser p, DeserializationContext ctxt) throws IOException {
 		String friendlyIdString = p.getValueAsString();
-		return FriendlyId.fromString(friendlyIdString);
+		return FriendlyId.parse(friendlyIdString);
 	}
 }
diff --git a/friendly-id-jooq/src/main/java/com/devskiller/friendly_id/jooq/FriendlyIdConverter.java b/friendly-id-jooq/src/main/java/com/devskiller/friendly_id/jooq/FriendlyIdConverter.java
@@ -44,7 +44,7 @@
  * <h2>Manual Usage Example</h2>
  * <pre>{@code
  * // Query using FriendlyId
- * FriendlyId friendlyId = FriendlyId.fromString("5wbwf6yUxVBcr48AMbz9cb");
+ * FriendlyId friendlyId = FriendlyId.parse("5wbwf6yUxVBcr48AMbz9cb");
  * UserRecord user = create
  *     .selectFrom(USER)
  *     .where(USER.ID.eq(friendlyId))
diff --git a/friendly-id-jooq/src/test/java/com/devskiller/friendly_id/jooq/FriendlyIdConverterTest.java b/friendly-id-jooq/src/test/java/com/devskiller/friendly_id/jooq/FriendlyIdConverterTest.java
@@ -27,7 +27,7 @@ void shouldConvertUuidToFriendlyId() {
 	@Test
 	void shouldConvertFriendlyIdToUuid() {
 		// given
-		FriendlyId friendlyId = FriendlyId.fromString("5wbwf6yUxVBcr48AMbz9cb");
+		FriendlyId friendlyId = FriendlyId.parse("5wbwf6yUxVBcr48AMbz9cb");
 
 		// when
 		UUID uuid = converter.to(friendlyId);
diff --git a/friendly-id-jpa/src/main/java/com/devskiller/friendly_id/jpa/FriendlyIdConverter.java b/friendly-id-jpa/src/main/java/com/devskiller/friendly_id/jpa/FriendlyIdConverter.java
@@ -42,7 +42,7 @@
  * <h2>Query Examples</h2>
  * <pre>{@code
  * // JPQL - use UUID parameter
- * FriendlyId userId = FriendlyId.fromString("5wbwf6yUxVBcr48AMbz9cb");
+ * FriendlyId userId = FriendlyId.parse("5wbwf6yUxVBcr48AMbz9cb");
  * User user = em.createQuery("SELECT u FROM User u WHERE u.id = :id", User.class)
  *     .setParameter("id", userId)
  *     .getSingleResult();
diff --git a/friendly-id-jpa/src/test/java/com/devskiller/friendly_id/jpa/FriendlyIdConverterTest.java b/friendly-id-jpa/src/test/java/com/devskiller/friendly_id/jpa/FriendlyIdConverterTest.java
@@ -15,7 +15,7 @@ class FriendlyIdConverterTest {
 	@Test
 	void shouldConvertFriendlyIdToUuid() {
 		// given
-		FriendlyId friendlyId = FriendlyId.fromString("5wbwf6yUxVBcr48AMbz9cb");
+		FriendlyId friendlyId = FriendlyId.parse("5wbwf6yUxVBcr48AMbz9cb");
 
 		// when
 		UUID uuid = converter.convertToDatabaseColumn(friendlyId);
diff --git a/friendly-id-openfeign/src/main/java/com/devskiller/friendly_id/openfeign/FriendlyIdDecoder.java b/friendly-id-openfeign/src/main/java/com/devskiller/friendly_id/openfeign/FriendlyIdDecoder.java
@@ -11,6 +11,8 @@
 import feign.codec.DecodeException;
 import feign.codec.Decoder;
 
+import static com.devskiller.friendly_id.type.FriendlyId.parse;
+
 /**
  * Feign decoder that converts FriendlyId strings to UUID and FriendlyId objects in responses.
  * <p>
@@ -45,7 +47,7 @@ public Object decode(Response response, Type type) throws IOException, DecodeExc
 		}
 
 		if (type == com.devskiller.friendly_id.type.FriendlyId.class && decoded instanceof String stringValue) {
-			return com.devskiller.friendly_id.type.FriendlyId.fromString(stringValue);
+			return parse(stringValue);
 		}
 
 		return decoded;
diff --git a/friendly-id-spring-boot/src/main/java/com/devskiller/friendly_id/spring/FriendlyIdConfiguration.java b/friendly-id-spring-boot/src/main/java/com/devskiller/friendly_id/spring/FriendlyIdConfiguration.java
@@ -34,7 +34,7 @@ public void addFormatters(FormatterRegistry registry) {
 		registry.addConverter(String.class, UUID.class, id -> toUuid(id));
 		registry.addConverter(UUID.class, String.class, id -> toFriendlyId(id));
 		registry.addConverter(String.class, com.devskiller.friendly_id.type.FriendlyId.class,
-				com.devskiller.friendly_id.type.FriendlyId::fromString);
+				com.devskiller.friendly_id.type.FriendlyId::parse);
 		registry.addConverter(com.devskiller.friendly_id.type.FriendlyId.class, String.class,
 				com.devskiller.friendly_id.type.FriendlyId::toString);
 	}
diff --git a/friendly-id/src/main/java/com/devskiller/friendly_id/type/FriendlyId.java b/friendly-id/src/main/java/com/devskiller/friendly_id/type/FriendlyId.java
@@ -39,19 +39,23 @@
  * FriendlyId id = FriendlyId.of(uuid);
  *
  * // Create from String
- * FriendlyId id = FriendlyId.fromString("5wbwf6yUxVBcr48AMbz9cb");
+ * FriendlyId id = FriendlyId.parse("5wbwf6yUxVBcr48AMbz9cb");
  *
  * // Create random
  * FriendlyId id = FriendlyId.random();
  *
+ * // Static import friendly
+ * import static com.devskiller.friendly_id.type.FriendlyId.friendlyId;
+ * FriendlyId id = friendlyId(uuid);
+ *
  * // Get UUID
- * UUID uuid = id.uuid();
+ * UUID uuid = id.toUuid();
  *
- * // Get FriendlyId string (computed on demand)
- * String friendlyIdString = id.toString();
+ * // Get FriendlyId string
+ * String friendlyIdString = id.value();
  * }</pre>
  *
- * @since 1.1.1
+ * @since 2.0
  */
 public final class FriendlyId implements Serializable, Comparable<FriendlyId> {
 
@@ -75,16 +79,50 @@ public static FriendlyId of(UUID uuid) {
 	}
 
 	/**
-	 * Creates a FriendlyId from a FriendlyId string representation.
+	 * Creates a FriendlyId from a UUID.
+	 * <p>
+	 * This method is designed for static imports:
+	 * <pre>{@code
+	 * import static com.devskiller.friendly_id.type.FriendlyId.friendlyId;
+	 * FriendlyId id = friendlyId(uuid);
+	 * }</pre>
 	 *
-	 * @param friendlyId the FriendlyId string to decode, must not be null
+	 * @param uuid the UUID to wrap, must not be null
 	 * @return a new FriendlyId instance
-	 * @throws NullPointerException if friendlyId is null
-	 * @throws IllegalArgumentException if friendlyId is not a valid FriendlyId
+	 * @throws NullPointerException if uuid is null
 	 */
-	public static FriendlyId fromString(String friendlyId) {
-		Objects.requireNonNull(friendlyId, "FriendlyId string cannot be null");
-		return new FriendlyId(com.devskiller.friendly_id.FriendlyId.toUuid(friendlyId));
+	public static FriendlyId friendlyId(UUID uuid) {
+		return new FriendlyId(uuid);
+	}
+
+	/**
+	 * Parses a string representation to FriendlyId.
+	 * <p>
+	 * Accepts both FriendlyId format (e.g., "5wbwf6yUxVBcr48AMbz9cb") and
+	 * standard UUID format (e.g., "c3587ec5-0976-497f-8374-61e0c2ea3da5").
+	 *
+	 * @param value the FriendlyId or UUID string to parse, must not be null
+	 * @return a new FriendlyId instance
+	 * @throws NullPointerException if value is null
+	 * @throws IllegalArgumentException if value is not a valid FriendlyId or UUID
+	 */
+	public static FriendlyId parse(String value) {
+		Objects.requireNonNull(value, "Value cannot be null");
+		if (isStandardUuidFormat(value)) {
+			return new FriendlyId(UUID.fromString(value));
+		}
+		return new FriendlyId(com.devskiller.friendly_id.FriendlyId.toUuid(value));
+	}
+
+	/**
+	 * Checks if the string matches standard UUID format (36 chars with hyphens).
+	 */
+	private static boolean isStandardUuidFormat(String value) {
+		return value.length() == 36
+				&& value.charAt(8) == '-'
+				&& value.charAt(13) == '-'
+				&& value.charAt(18) == '-'
+				&& value.charAt(23) == '-';
 	}
 
 	/**
@@ -101,10 +139,32 @@ public static FriendlyId random() {
 	 *
 	 * @return the UUID
 	 */
+	public UUID toUuid() {
+		return uuid;
+	}
+
+	/**
+	 * Returns the underlying UUID.
+	 * <p>
+	 * This is an alias for {@link #toUuid()} following record-style naming.
+	 *
+	 * @return the UUID
+	 */
 	public UUID uuid() {
 		return uuid;
 	}
 
+	/**
+	 * Returns the FriendlyId string representation.
+	 * <p>
+	 * The string is computed on demand from the internal UUID.
+	 *
+	 * @return the FriendlyId string
+	 */
+	public String value() {
+		return com.devskiller.friendly_id.FriendlyId.toFriendlyId(uuid);
+	}
+
 	/**
 	 * Returns the FriendlyId string representation.
 	 * <p>
@@ -115,7 +175,7 @@ public UUID uuid() {
 	 */
 	@Override
 	public String toString() {
-		return com.devskiller.friendly_id.FriendlyId.toFriendlyId(uuid);
+		return value();
 	}
 
 	@Override
diff --git a/friendly-id/src/test/java/com/devskiller/friendly_id/type/FriendlyIdTest.java b/friendly-id/src/test/java/com/devskiller/friendly_id/type/FriendlyIdTest.java

Original file line number	Diff line number	Diff line change
`@@ -19,6 +19,6 @@ public FriendlyIdValueDeserializer() {`
`19`	`19`	`@Override`
`20`	`20`	`public FriendlyId deserialize(JsonParser p, DeserializationContext ctxt) {`
`21`	`21`	`String friendlyIdString = p.getString();`
`22`		`- return FriendlyId.fromString(friendlyIdString);`
	`22`	`+ return FriendlyId.parse(friendlyIdString);`
`23`	`23`	`}`
`24`	`24`	`}`
Original file line number	Diff line number	Diff line change
`@@ -17,6 +17,6 @@ public class FriendlyIdValueDeserializer extends JsonDeserializer<FriendlyId> {`
`17`	`17`	`@Override`
`18`	`18`	`public FriendlyId deserialize(JsonParser p, DeserializationContext ctxt) throws IOException {`
`19`	`19`	`String friendlyIdString = p.getValueAsString();`
`20`		`- return FriendlyId.fromString(friendlyIdString);`
	`20`	`+ return FriendlyId.parse(friendlyIdString);`
`21`	`21`	`}`
`22`	`22`	`}`
Original file line number	Diff line number	Diff line change
`@@ -11,6 +11,8 @@`
`11`	`11`	`import feign.codec.DecodeException;`
`12`	`12`	`import feign.codec.Decoder;`
`13`	`13`
	`14`	`+import static com.devskiller.friendly_id.type.FriendlyId.parse;`
	`15`	`+`
`14`	`16`	`/**`
`15`	`17`	`* Feign decoder that converts FriendlyId strings to UUID and FriendlyId objects in responses.`
`16`	`18`	`* <p>`
`@@ -45,7 +47,7 @@ public Object decode(Response response, Type type) throws IOException, DecodeExc`
`45`	`47`	`}`
`46`	`48`
`47`	`49`	`if (type == com.devskiller.friendly_id.type.FriendlyId.class && decoded instanceof String stringValue) {`
`48`		`- return com.devskiller.friendly_id.type.FriendlyId.fromString(stringValue);`
	`50`	`+ return parse(stringValue);`
`49`	`51`	`}`
`50`	`52`
`51`	`53`	`return decoded;`
Original file line number	Diff line number	Diff line change
`@@ -34,7 +34,7 @@ public void addFormatters(FormatterRegistry registry) {`
`34`	`34`	`registry.addConverter(String.class, UUID.class, id -> toUuid(id));`
`35`	`35`	`registry.addConverter(UUID.class, String.class, id -> toFriendlyId(id));`
`36`	`36`	`registry.addConverter(String.class, com.devskiller.friendly_id.type.FriendlyId.class,`
`37`		`- com.devskiller.friendly_id.type.FriendlyId::fromString);`
	`37`	`+ com.devskiller.friendly_id.type.FriendlyId::parse);`
`38`	`38`	`registry.addConverter(com.devskiller.friendly_id.type.FriendlyId.class, String.class,`
`39`	`39`	`com.devskiller.friendly_id.type.FriendlyId::toString);`
`40`	`40`	`}`