diff --git a/packages/forms/src/validators.ts b/packages/forms/src/validators.ts index 68b947ced8..a15ee595e8 100644 --- a/packages/forms/src/validators.ts +++ b/packages/forms/src/validators.ts @@ -57,6 +57,36 @@ export const NG_VALIDATORS = new InjectionToken>('NgVa export const NG_ASYNC_VALIDATORS = new InjectionToken>('NgAsyncValidators'); +/** + * A regular expression that matches valid e-mail addresses. + * + * At a high level, this regexp matches e-mail addresses of the format `local-part@tld`, where: + * - `local-part` consists of one or more of the allowed characters (alphanumeric and some + * punctuation symbols). + * - `local-part` cannot begin or end with a period (`.`). + * - `local-part` cannot be longer than 64 characters. + * - `tld` consists of one or more `labels` separated by periods (`.`). For example `localhost` or + * `foo.com`. + * - A `label` consists of one or more of the allowed characters (alphanumeric, dashes (`-`) and + * periods (`.`)). + * - A `label` cannot begin or end with a dash (`-`) or a period (`.`). + * - A `label` cannot be longer than 63 characters. + * - The whole address cannot be longer than 254 characters. + * + * ## Implementation background + * + * This regexp was ported over from AngularJS (see there for git history): + * https://github.com/angular/angular.js/blob/c133ef836/src/ng/directive/input.js#L27 + * It is based on the + * [WHATWG version](https://html.spec.whatwg.org/multipage/input.html#valid-e-mail-address) with + * some enhancements to incorporate more RFC rules (such as rules related to domain names and the + * lengths of different parts of the address). The main differences from the WHATWG version are: + * - Disallow `local-part` to begin or end with a period (`.`). + * - Disallow `local-part` length to exceed 64 characters. + * - Disallow total address length to exceed 254 characters. + * + * See [this commit](https://github.com/angular/angular.js/commit/f3f5cf72e) for more details. + */ const EMAIL_REGEXP = /^(?=.{1,254}$)(?=.{1,64}@)[-!#$%&'*+/0-9=?A-Z^_`a-z{|}~]+(\.[-!#$%&'*+/0-9=?A-Z^_`a-z{|}~]+)*@[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$/; @@ -191,6 +221,20 @@ export class Validators { * @description * Validator that requires the control's value pass an email validation test. * + * Tests the value using a [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) + * pattern suitable for common usecases. The pattern is based on the definition of a valid email + * address in the [WHATWG HTML specification](https://html.spec.whatwg.org/multipage/input.html#valid-e-mail-address) + * with some enhancements to incorporate more RFC rules (such as rules related to domain names and + * the lengths of different parts of the address). + * + * The differences from the WHATWG version include: + * - Disallow `local-part` (the part before the `@` symbol) to begin or end with a period (`.`). + * - Disallow `local-part` to be longer than 64 characters. + * - Disallow the whole address to be longer than 254 characters. + * + * If this pattern does not satisfy your business needs, you can use `Validators.pattern()` to + * validate the value against a different pattern. + * * @usageNotes * * ### Validate that the field matches a valid email pattern