💡 The `EmailAddress` type

[LVMVRQUXL]

📝 Description

Like suggested by @MichaelStH in #55, we would like to introduce a new EmailAddress type representing an email address on the Internet.

Here's the goal of API that we should provide after completing this topic:

interface EmailAddress {
    override fun equals(other: Any?): Boolean
    override fun hashCode(): Int
    override fun toString(): String
    
    companion object {
        fun create(text: String): EmailAddress
        fun create(text: String, regex: Regex): EmailAddress
        fun createOrNull(text: String): EmailAddress?
        fun createOrNull(text: String, regex: Regex): EmailAddress?
    }
}

✅ Checklist

• ✨ New EmailAddress type #339
• 🚚 Moving EmailAddress type to kotools.types.web package #377
• ✨ EmailAddress syntax should follow RFC-5322 #394
• 🦺 Support digits in local-part of EmailAddress #581
• 🦺 Support hyphens and underscores in local-part of EmailAddress #583
• 🦺 Limiting number of characters in local-part of EmailAddress #582
• 💥 Signature changes to the regular expression of EmailAddress #593
• ✨ Making EmailAddress.Companion.regexPattern available on Java #594
• ⏪️ Going back to a simpler regular expression for EmailAddress #600
• 🔥 Deletion of EmailAddress.Companion.regex property #614
• ✨ New factory functions for EmailAddress accepting a custom regular expression #601
• ✨ Stabilization of EmailAddress type #369
• Close this topic as completed and update tracking issues if present.

The following issues are nice-to-have but not required for completing the minimum viable API of this type:

• ✨ Making EmailAddress comparable alphabetically #595

[LVMVRQUXL]

See #55 (reply in thread) for improving the API of this type.

[LVMVRQUXL]

A solution for providing the pattern used for validating an EmailAddress to Kotlin and Java is to declare it as a String instead of a Regex.

// Before
val EmailAddress.Companion.regex: Regex
// After
val EmailAddress.Companion.regexPattern: String // or EmailAddress.Regex.pattern

It can also be declared as a NotBlankString, but its stabilization will be blocked by the issue #404.

// Before
val EmailAddress.Companion.regex: Regex
// After
val EmailAddress.Companion.regexPattern: NotBlankString // or EmailAddress.Regex.pattern

[LVMVRQUXL]

Another idea for improving this type is to make it comparable alphabetically like the NotBlankString type.

[LVMVRQUXL]

A better approach to validating email addresses is to use a simpler regular expression by default, like ^\S+@\S+\.\S+$ and to provide an overload of the factory functions accepting a custom regular expression.

EmailAddress.create("contact@kotools.org") // uses the default regular expression
EmailAddress.create("contact@kotools.org", Regex("^[a-z]+@[a-z]+\\.[a-z]+$")) // uses the specified regular expression

For validating the custom regular expression, the trick is to check that the given pattern matches the default regular expression. If that's the case, then we should consider the customized regular expression valid.

val result: Boolean = "^[a-z]+@[a-z]+\\.[a-z]+$" matches Regex("^\\S+@\\S+\\.\\S+$")
println(result) // true

[LVMVRQUXL]

Comment related to #601.

For making the factory functions accepting a custom regular expression available on Kotlin and on Java, we could change their signature for accepting a custom pattern as Any. This way, these functions will use the string representation of the specified pattern as regular expression.

fun EmailAddress.Companion.create(text: String, pattern: Any): EmailAddress
fun EmailAddress.Companion.createOrNull(text: String, pattern: Any): EmailAddress?

Important

Due to the unique behavior of the Regex.toString() function on Kotlin/JS, it is recommended to use the Regex.pattern property instead.

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

val regex = Regex("^[a-z]+@[a-z]+\\.[a-z]+$")
EmailAddress.create("contact@kotools.org", regex.pattern) // passes
EmailAddress.create(" @kotools.org", regex.pattern) // fails

[LVMVRQUXL]

Related issue: #614.

For hiding implementation details, an option is to remove the EmailAddress.Companion.regexPattern property from the public API, and indicate the pattern used for validating email addresses directly in the documentation of the factory functions.

Here's an example of documentation for the EmailAddress.Companion.create(String) function:

/**
 * Creates an email address from the specified [text], or throws an [IllegalArgumentException]
 * if the [text] doesn't match the following regular expression: `^\S+@\S+\.\S+$`.
 */
fun EmailAddress.Companion.create(text: String): EmailAddress = TODO()

[LVMVRQUXL]

Duplicates #616.

For improving the consistency of our API, we could rename the text argument of the factory functions as value.
Here's an example for the EmailAddress.Companion.create(String) function:

fun EmailAddress.Companion.create(value: String): EmailAddress = TODO()