✨ New `EmailAddress` type in `org.kotools.types` package

[LVMVRQUXL]

📝 Description

We want to introduce an EmailAddress experimental type, in the org.kotools.types package of the types Gradle subproject, with an improved API for deprecating the same type from the kotools.types.web package.

interface EmailAddress {
    override fun equals(other: Any?): Boolean
    override fun hashCode(): Int
    override fun toString(): String

    companion object {
        const val PATTERN: String

        fun fromString(value: Any): EmailAddress
        fun fromString(value: Any, pattern: Any): EmailAddress

        fun fromStringOrNull(value: Any): EmailAddress?
        fun fromStringOrNull(value: Any, pattern: Any): EmailAddress?
    }
}

Like the type from the kotools.types.web package, this new one should be serializable as String. Finally, we want to deprecate the type from the kotools.types.web with a warning level, and its factory functions with an error level and replacement suggestions, for removal in v4.7.

✅ Checklist

• [x] ✨ Add the type in the org.kotools.types package and dump the Application Binary Interface (ABI).
• [x] ✨ Add the PATTERN constant, test this constant, add Kotlin and Java code samples for this constant, and dump the ABI.
• [x] ✨ Add the fromStringOrNull(Any) function with tests, code samples for Kotlin and Java, reference it in the type's documentation and dump the ABI.
• [x] ✨ Add the fromString(Any) function with tests, code samples for Kotlin and Java, reference it in the type's documentation and dump the ABI.
• [x] ✨ Add the fromStringOrNull(Any, Any) function with tests, code samples for Kotlin and Java, and dump the ABI.
• [x] ✨ Add the fromString(Any, Any) function with tests, code samples for Kotlin and Java, and dump the ABI.
• [x] ✨ Add the toString function with tests, code samples for Kotlin and Java, and dump the ABI.
• [x] ✨ Add structural equality operations (equals and hashCode) with tests, code samples for Kotlin and Java, and dump the ABI.
• [x] ✨ Make the type serializable as String with tests, Kotlin code sample and dump the ABI.
• [x] 🗑️ Deprecate the EmailAddress type from the kotools.types.web package with a warning level, and its factory functions with an error level and replacement suggestions, for removal in v4.7. This is a source incompatible change.
• [x] 📝 Add an entry for this issue in the unreleased changelog.
• [x] 🔥 Remove outdated entries from the unreleased changelog.
• [x] 📝 Create an issue for removing the EmailAddress type from the kotools.types.web package in v4.7.
• [x] ✨ Add the KotoolsTypesSerializers.emailAddress property for serializing this type as String, with documentation, tests, samples, then dump the corresponding ABI.
• [x] 🔥 Remove the @Serializable annotation from this type, its serialization tests and documentation, then dump the ABI.
• [x] ✨ Include the KotoolsTypesSerializers.emailAddress module in the KotoolsTypesSerializers.all one with tests.

[LVMVRQUXL]

Also related to issue #602.

It may be a good idea to extract serializers to a new kotlinx-serialization subproject while making this type serializable. Consumers will be able to import the new subproject and use it like the following:

val format = Json { serializersModule = KotoolsTypesSerializersModule.all }
val emailAddress = format.decodeFromString<EmailAddress>("\"contact@kotools.org\"")
println(emailAddress) // contact@kotools.org

[LVMVRQUXL]

A better design for creating instances of the EmailAddress type is to provide constructors that should throw exceptions in case of invalid arguments, and orNull factory functions that should return null in case of invalid arguments. Also, arguments should be of type String instead of Any for avoiding confusions.

fun EmailAddress(value: String): EmailAddress
fun EmailAddress(value: String, pattern: String): EmailAddress

fun EmailAddress.Companion.orNull(value: String): EmailAddress?
fun EmailAddress.Companion.orNull(value: String, pattern: String): EmailAddress?

Here are some examples for calling these functions from Kotlin code:

EmailAddress("contact@kotools.org")
EmailAddress(" @kotools.org") // throws an exception

EmailAddress(value = "contact@kotools.org", pattern = "^[a-z]+@[a-z]+\\.[a-z]+\$")
EmailAddress(value = " @kotools.org", pattern = "^[a-z]+@[a-z]+\\.[a-z]+\$") // throws an exception
EmailAddress(value = "contact@kotools.org", pattern = "^[a-z]+\$") // throws an exception

EmailAddress.orNull("contact@kotools.org")
EmailAddress.orNull(" @kotools.org") // returns null

EmailAddress.orNull(value = "contact@kotools.org", pattern = "^[a-z]+@[a-z]+\\.[a-z]+\$")
EmailAddress.orNull(value = " @kotools.org", pattern = "^[a-z]+@[a-z]+\\.[a-z]+\$") // returns null
EmailAddress.orNull(value = "contact@kotools.org", pattern = "^[a-z]+\$") // returns null

Finally, the EmailAddress(String) function should be the primary constructor.

[LVMVRQUXL]

It is not possible to define another constructor without directly calling the primary one, including the check of the value against the default pattern, which is not the intended behavior when calling the factory function of EmailAddress with a custom pattern. So we will go back to the original factory functions.