✨ New EmailAddress type

[MichaelStH]

Suggesting to create a new type Email handling email string, regex pattern

[LVMVRQUXL]

Thank you for suggesting this new type @MichaelStH!

Here's an article that could help for defining an email address.
Accordingly to this article, an email address could be defined as local-part@domain.
It means that we need to check if the string contains exactly one @ for being a valid email address.

I have several questions:

• how would you like to create the Email type? We could do the following:

"user" at "example.com" // 1 - returns an Email
"user@example.com".toEmail() // 2 - returns a Result<Email> because the String could be invalid

• also, do you have any need on what this type should do?

[LVMVRQUXL]

@MichaelStH I assume that your thumb up means that you would like to create the Email type with the suggested builders.
I will create an issue for implementing this new type and will let you know on this discussion about it.

[LVMVRQUXL]

@MichaelStH I've found the regex pattern matching email addresses: ^[\w-.]+@([\w-]+\.)+[\w-]{2,4}$ (you can test it here).
Here's the minimal API that we would like to implement for the new Email type:

fun String.toEmail(): Result<Email> = TODO()
fun NotBlankString.toEmail(): Result<Email> = TODO()

sealed interface Email {
    override fun toString(): String
    fun toNotBlankString(): NotBlankString
}

Notice that we will not implement the first builder proposed (with at infix function) for being consistent with the rest of the code in this library.

Please let me know your thoughts on this.

[MichaelStH]

I think that this implementation is correct

[LVMVRQUXL]

Here's an updated regular expression matching email addresses with more precision: ^([a-zA-Z]+(?:[-_\.][a-zA-Z]+)*)@([a-zA-Z]+(?:[-_][a-zA-Z]+)*\.[a-zA-Z]+(?:[-_][a-zA-Z]+)*)$.

[LVMVRQUXL]

It feels like the naming of the type suggested by @MichaelStH is not accurate.
Accordingly to Wikipedia, an email is an electronic mail and an email address is an inbox storing emails.
So, because the goal is to represent email addresses with a type, I suggest to rename it from Email to EmailAddress.

[MichaelStH]

Yes I agree, this is a good point and more accurate accordingly to Wikipedia's definition.

[LVMVRQUXL]

Thank you @MichaelStH for sharing your thoughts on this.
Here's an update on the minimal API that we would like to implement for representing an email address:

/**
 * Returns this string as an encapsulated [EmailAddress], or returns an
 * encapsulated [IllegalArgumentException] if this string is blank or invalid.
 */
fun String.toEmail(): Result<EmailAddress> = TODO()

/**
 * Returns this string as an encapsulated [EmailAddress], or returns an
 * encapsulated [IllegalArgumentException] if this string is invalid.
 */
fun NotBlankString.toEmail(): Result<EmailAddress> = TODO()

/** Represents an email address. */
interface EmailAddress { // could be an inline class
    /** Returns this email address as a [String]. */
    override fun toString(): String

    /** Returns this email address as a [NotBlankString]. */
    fun toNotBlankString(): NotBlankString
}

I will add a new comment for summarizing the idea and listing a checklist for integrating it in the library.

[LVMVRQUXL]

The API of this new EmailAddress may change with the integration of the idea #104 on aligning builders with the Kotlin standards.

[LVMVRQUXL]

@MichaelStH Are you okay with the following API?

/**
 * Returns this string as an [EmailAddress], or throws an
 * [IllegalArgumentException] if this string is blank or invalid.
 */
fun String.toEmail(): EmailAddress = TODO()

/**
 * Returns this string as an [EmailAddress], or returns `null`
 * if this string is blank or invalid.
 */
fun String.toEmailOrNull(): EmailAddress? = TODO()

/**
 * Returns this string as an [EmailAddress], or throws an
 * [IllegalArgumentException] if this string is invalid.
 */
fun NotBlankString.toEmail(): EmailAddress = TODO()

/**
 * Returns this string as an [EmailAddress], or returns `null`
 * if this string is invalid.
 */
fun NotBlankString.toEmailOrNull(): EmailAddress? = TODO()

/** Represents an email address. */
interface EmailAddress { // could be an inline class
    /**
     * The local part of this email address.
     * This is usually the part **before** the `@` character.
     */
    val localPart: NotBlankString

    /**
     * The domain of this email address.
     * This is usually the part **after** the `@` character.
     */
    val domain: NotBlankString

    /** Returns this email address as a [String]. */
    override fun toString(): String

    /** Returns this email address as a [NotBlankString]. */
    fun toNotBlankString(): NotBlankString
}

[LVMVRQUXL]

@MichaelStH For your information, we have created the issue #339 for introducing the type EmailAddress as an experimental feature. 👀

[MichaelStH]

Niice, can't wait to see that feature, or maybe collaborate on this if it is possible

[LVMVRQUXL]

Sure @MichaelStH, any type of contribution is welcomed!

The issue #339 will provide a minimal API for this type. So feel free to make additional suggestions for improving this type by making another feature suggestion depending on the issue #339.

Some interesting comments about this type that you may be interested in:

• ✨ New EmailAddress type #339 (comment) The final regular expression for validating email addresses.
• ✨ New EmailAddress type #339 (comment) We are still thinking about the type that should represent the local part of an email address, but we will create issues for adding the domain and length properties to EmailAddress at the end of this issue's resolution.
• ✨ New EmailAddress type #339 (comment) We are also thinking ways for customizing the default regular expression.

Feel free to react directly in comments of the issue #339 if you have an idea around the topics listed above.

[LVMVRQUXL]

We are reopening this discussion for tracking issues related to this project of adding the EmailAddress type.

• ✨ 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
• 🦺 Limiting number of characters in local-part of EmailAddress #582
• 🦺 Support hyphens and underscores in local-part of EmailAddress #583
• ✨ Stabilization of EmailAddress type #369

This discussion will be closed as completed after completing issues listed above.

[LVMVRQUXL]

The following issues are good candidates for improving the API of the EmailAddress type:

• New EmailAddress.length property #357
• New EmailAddress.domain property #358
• New EmailAddress.toNotBlankString() function #359
• New EmailAddress.localPart property #387
• ✨ New factory functions with configurable regular expression for EmailAddress #388

[LVMVRQUXL]

We've created the issue #586 for tracking those related to this topic.
We can close this discussion as completed.