@email-utils/validator-syntax 1.0.0-rc.1 → 1.0.0-rc.2

package/dist/index.mjs

@@ -1,6 +1,18 @@
+//#region src/chars.ts
+const charCodeAt = String.prototype.charCodeAt;
+/**
+* `text.charCodeAt(i)`, through the builtin itself. Called as a method,
+* `charCodeAt` is looked up on the string, and a call site that has seen
+* enough kinds of string (one-byte and two-byte, flat, sliced, and
+* concatenated) goes megamorphic: V8 stops inlining it, and after arbitrary
+* Unicode input every scan ran 2–3× slower (validator-syntax#15).
+*/
+function codeAt(text, i) {
+	return charCodeAt.call(text, i);
+}
 const table = /* @__PURE__ */ new Uint8Array(128);
 function mark(chars, flag) {
-	for (let i = 0; i < chars.length; i++) table[chars.charCodeAt(i)] |= flag;
+	for (let i = 0; i < chars.length; i++) table[codeAt(chars, i)] |= flag;
 }
 const alnum = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
 mark(alnum + "!#$%&'*+-/=?^_`{|}~", 1);
@@ -21,22 +33,35 @@ function isWhitespace(code) {
 * lone surrogate, which no UTF-8 text can hold.
 */
 function nonAsciiAt(text, i, end) {
-	const code = text.charCodeAt(i);
+	const code = codeAt(text, i);
 	if (code < 128 || code >= 56320 && code <= 57343) return 0;
 	if (code < 55296 || code > 56319) return 1;
-	const low = i + 1 < end ? text.charCodeAt(i + 1) : 0;
+	const low = i + 1 < end ? codeAt(text, i + 1) : 0;
 	return low >= 56320 && low <= 57343 ? 2 : 0;
 }
 /** The length of `text` in UTF-8 octets, the unit RFC 6531 caps a local part in. */
 function utf8Length(text) {
-	let octets = text.length;
-	for (let i = 0; i < text.length; i++) {
-		const code = text.charCodeAt(i);
+	const end = text.length;
+	let octets = end;
+	for (let i = 0; i < end; i++) {
+		const code = codeAt(text, i);
 		if (code >= 2048 && (code < 55296 || code > 57343)) octets += 2;
 		else if (code >= 128) octets += 1;
 	}
 	return octets;
 }
+/**
+* The code points in `text` from `start` to `end`, which must not split a
+* surrogate pair: its length with each pair counted once.
+*/
+function codePoints(text, start, end) {
+	let count = end - start;
+	for (let i = start; i < end; i++) {
+		const code = codeAt(text, i);
+		if (code >= 56320 && code <= 57343) count--;
+	}
+	return count;
+}
 //#endregion
 //#region src/options.ts
 const presets = {
@@ -52,7 +77,8 @@ const presets = {
 		checkTld: true,
 		allowNoTld: false,
 		unicode: false,
-		idn: false
+		idn: false,
+		maxLength: 512
 	},
 	rfc5321: {
 		local: 1,
@@ -66,7 +92,8 @@ const presets = {
 		checkTld: false,
 		allowNoTld: false,
 		unicode: false,
-		idn: false
+		idn: false,
+		maxLength: 512
 	},
 	rfc5322: {
 		local: 1,
@@ -80,7 +107,8 @@ const presets = {
 		checkTld: false,
 		allowNoTld: false,
 		unicode: false,
-		idn: false
+		idn: false,
+		maxLength: 512
 	},
 	html5: {
 		local: 4,
@@ -94,7 +122,8 @@ const presets = {
 		checkTld: false,
 		allowNoTld: true,
 		unicode: false,
-		idn: false
+		idn: false,
+		maxLength: 512
 	}
 };
 const overrides = [
@@ -120,13 +149,14 @@ const unsupported = {
 * Resolves `options` into the rules they select.
 *
 * @throws TypeError when `options` isn't an object, names an unknown option
-* or preset, gives a non-boolean override, or turns on something the
-* preset's grammar has no room for.
+* or preset, gives a non-boolean override or a `maxLength` that isn't a
+* positive integer or `Infinity`, or turns on something the preset's grammar
+* has no room for.
 */
 function resolve(options) {
 	if (options === void 0) return presets.practical;
 	if (typeof options !== "object" || options === null) throw new TypeError("Expected the options to be an object");
-	for (const key of Object.keys(options)) if (key !== "preset" && !overrides.includes(key)) throw new TypeError(`Unknown option: ${key}`);
+	for (const key of Object.keys(options)) if (key !== "preset" && key !== "maxLength" && !overrides.includes(key)) throw new TypeError(`Unknown option: ${key}`);
 	const preset = options.preset ?? "practical";
 	if (!Object.hasOwn(presets, preset)) throw new TypeError(`Unknown preset: ${preset}`);
 	const base = presets[preset];
@@ -134,8 +164,10 @@ function resolve(options) {
 		const value = options[key];
 		if (value !== void 0 && typeof value !== "boolean") throw new TypeError(`Expected ${key} to be a boolean`);
 	}
+	const { maxLength } = options;
+	if (maxLength !== void 0 && maxLength !== Infinity && !(Number.isInteger(maxLength) && maxLength > 0)) throw new TypeError("Expected maxLength to be a positive integer or Infinity");
 	for (const key of unsupported[preset]) if (options[key] === true) throw new TypeError(`${key} can’t be true with the ${preset} preset`);
-	if (overrides.every((key) => options[key] === void 0)) return base;
+	if (maxLength === void 0 && overrides.every((key) => options[key] === void 0)) return base;
 	return {
 		...base,
 		checkTld: options.checkTld ?? base.checkTld,
@@ -143,13 +175,27 @@ function resolve(options) {
 		comments: options.allowComments ?? base.comments,
 		unicode: options.allowUnicode ?? base.unicode,
 		idn: options.allowIdn ?? base.idn,
-		literals: options.allowIpLiteral ?? base.literals
+		literals: options.allowIpLiteral ?? base.literals,
+		maxLength: maxLength ?? base.maxLength
 	};
 }
 //#endregion
 //#region src/idn.ts
 const ldh = /^[\da-z-]+$/;
 /**
+* The hostname of `http://x.` and `host`, or `undefined` when the WHATWG URL
+* parser rejects it. `URL.parse` says so without the cost of throwing, a few
+* µs a time, so an address built to fail many conversions stays fast;
+* runtimes that predate it (Node before 22.1) throw instead.
+*/
+const hostnameOf = typeof URL.parse === "function" ? (host) => URL.parse(`http://x.${host}`)?.hostname : (host) => {
+	try {
+		return new URL(`http://x.${host}`).hostname;
+	} catch {
+		return;
+	}
+};
+/**
 * The A-label for a U-label, or `undefined` when UTS #46 rejects it or maps
 * it to something other than one IDN label (plain ASCII, or two labels, as
 * `。` becomes a dot).
@@ -160,14 +206,65 @@ const ldh = /^[\da-z-]+$/;
 * checks. It leaves hyphens and lengths alone, so the caller checks those.
 */
 function toALabel(label) {
-	let host;
-	try {
-		host = new URL(`http://x.${label}`).hostname;
-	} catch {
-		return;
+	const aLabel = hostnameOf(label)?.slice(2);
+	return aLabel?.startsWith("xn--") === true && ldh.test(aLabel) ? aLabel : void 0;
+}
+const rtl = /[\u0590-\u08ff\u2135-\u2138\ufb1d-\ufdff\ufe70-\ufeff\u{10800}-\u{10fff}\u{1e800}-\u{1efff}]/u;
+/**
+* The A-label for each U-label in `labels`, as {@link toALabel} gives it,
+* converted as few domains as it can: one URL costs about as much as one
+* label does.
+*
+* @remarks
+* Every entry up to the first `undefined` is exact; entries after it may be
+* left `undefined` unconverted. Converted together, a right-to-left label
+* would hold the others to RFC 5893's rules too, which it doesn't alone, so
+* right-to-left labels go in a domain of their own. Converting more labels
+* at once only adds rules, so a domain that converts means every label
+* would alone; one that doesn't is narrowed down to its first label that
+* fails alone.
+*/
+function toALabels(labels) {
+	if (!labels.some((label) => rtl.test(label))) return convertGroup(labels);
+	const aLabels = labels.map(() => void 0);
+	for (const bidi of [false, true]) {
+		const members = [];
+		labels.forEach((label, k) => {
+			if (rtl.test(label) === bidi) members.push(k);
+		});
+		if (members.length > 0) convertGroup(members.map((k) => labels[k])).forEach((aLabel, j) => {
+			aLabels[members[j]] = aLabel;
+		});
 	}
-	const aLabel = host.slice(2);
-	return aLabel.startsWith("xn--") && ldh.test(aLabel) ? aLabel : void 0;
+	return aLabels;
+}
+/** {@link toALabels} for labels converted together. */
+function convertGroup(labels) {
+	const all = convert(labels);
+	if (all !== void 0) return all;
+	let pass = [];
+	let failing = labels.length;
+	while (failing - pass.length > 1) {
+		const some = convert(labels.slice(0, pass.length + failing >> 1));
+		if (some === void 0) failing = pass.length + failing >> 1;
+		else pass = some;
+	}
+	const aLabels = pass;
+	for (let k = pass.length; k < labels.length; k++) {
+		const aLabel = toALabel(labels[k]);
+		aLabels.push(aLabel);
+		if (aLabel === void 0) break;
+	}
+	return aLabels;
+}
+const aLabelHost = /^x(?:\.xn--[\da-z-]+)+$/;
+/** `labels` converted as one domain, or `undefined`. */
+function convert(labels) {
+	const hostname = hostnameOf(labels.join("."));
+	if (hostname === void 0 || !aLabelHost.test(hostname)) return;
+	const aLabels = hostname.split(".");
+	aLabels.shift();
+	return aLabels.length === labels.length ? aLabels : void 0;
 }
 //#endregion
 //#region src/ip.ts
@@ -175,6 +272,7 @@ const octet = /^\d{1,3}$/;
 const hexGroup = /^[\dA-Fa-f]{1,4}$/;
 /** An IPv4 address: four dot-separated decimal octets, each 0–255. */
 function isIPv4(text) {
+	if (text.length > 15) return false;
 	const parts = text.split(".");
 	return parts.length === 4 && parts.every((part) => octet.test(part) && Number(part) <= 255);
 }
@@ -184,6 +282,7 @@ function isIPv4(text) {
 * place of the last two groups.
 */
 function isIPv6(text) {
+	if (text.length > 45) return false;
 	const colon = text.lastIndexOf(":");
 	const tail = text.slice(colon + 1);
 	if (tail.includes(".")) {
@@ -1667,7 +1766,7 @@ const messages = {
 	"syntax.local.too_long": "The local part is longer than 64 characters",
 	"syntax.local.invalid_char": "The local part has a character it can’t hold",
 	"syntax.local.consecutive_dots": "The local part has two dots in a row",
-	"syntax.local.unquoted_space": "The local part has a space outside quotes",
+	"syntax.local.unquoted_space": "The local part has whitespace outside quotes",
 	"syntax.domain.empty": "Nothing comes after the @",
 	"syntax.domain.no_dot": "The domain has no dot",
 	"syntax.domain.label_invalid": "A domain label is empty, too long, or starts or ends with a hyphen",
@@ -1710,8 +1809,9 @@ function findAt(email, rules) {
 	let domainStart = false;
 	let depth = 0;
 	let at = -1;
-	for (let i = 0; i < email.length; i++) {
-		const code = email.charCodeAt(i);
+	const end = email.length;
+	for (let i = 0; i < end; i++) {
+		const code = codeAt(email, i);
 		if (state === NORMAL) {
 			if (code === 64) {
 				at = i;
@@ -1742,6 +1842,7 @@ function findAt(email, rules) {
 function parse(email, rules) {
 	if (typeof email !== "string") throw new TypeError(`Expected a string, got ${typeof email}`);
 	if (email === "") return fail("syntax.address.empty");
+	if (email.length > rules.maxLength) return fail("syntax.address.too_long");
 	const at = findAt(email, rules);
 	if (at < 0) return fail("syntax.address.no_at");
 	const comments = [];
@@ -1785,7 +1886,7 @@ function scanLocal(email, at, rules, comments) {
 	let trailing = comments.length;
 	let i = 0;
 	while (i < at) {
-		const code = email.charCodeAt(i);
+		const code = codeAt(email, i);
 		const quote = code === 34 && rules.quotes && (rules.obs || i === 0);
 		const atom = inClass(code, rules.local);
 		if (quote || atom || rules.unicode && nonAsciiAt(email, i, at) > 0) {
@@ -1798,10 +1899,10 @@ function scanLocal(email, at, rules, comments) {
 				closed = !rules.obs;
 			} else {
 				next = atom ? i + 1 : i;
-				while (next < at && inClass(email.charCodeAt(next), rules.local)) next++;
+				while (next < at && inClass(codeAt(email, next), rules.local)) next++;
 				if (rules.unicode) next = skipUnicode(email, next, at, rules.local);
 			}
-			local += unfold(email.slice(i, next));
+			local += unfold(email, i, next);
 			words++;
 			afterWord = true;
 			dot = -1;
@@ -1846,6 +1947,63 @@ function scanLocal(email, at, rules, comments) {
 * folding whitespace.
 */
 function scanDomain(email, at, rules, comments) {
+	const uLabels = [];
+	const domain = scanLabels(email, at, rules, comments, uLabels);
+	if (uLabels.length === 0) return domain;
+	const growth = checkULabels(email, uLabels, rules.domainCap);
+	if (typeof growth !== "number") return growth;
+	if (!("reason" in domain)) domain.size += growth;
+	return domain;
+}
+/**
+* Checks the U-labels at `spans`, triples of start, end, and the length of
+* the domain before it, as A-labels: each must convert, and pass the
+* hostname rules as its A-label. Returns the first failure, or what the
+* A-labels add to the domain's length: `Infinity` once it's past `cap`.
+*
+* @remarks
+* The U-labels are converted a few at a time, about 32 characters of them
+* in each URL: one URL costs about as much as one label alone, and a small
+* batch wastes little past the first failure or past `cap`. Once the
+* A-labels take the domain past `cap`, the rest aren't checked: the domain
+* fails as too long, unless the scan found something earlier. Punycode's
+* cost grows with the square of a label's length, so converting labels that
+* can't change the outcome would cost the most on input built to be slow
+* (validator-syntax#15).
+*/
+function checkULabels(email, spans, cap) {
+	let growth = 0;
+	for (let first = 0; first < spans.length;) {
+		const chunk = [];
+		let written = 0;
+		let next = first;
+		while (next < spans.length && written < 32) {
+			const label = email.slice(spans[next], spans[next + 1]);
+			chunk.push(label);
+			written += label.length;
+			next += 3;
+		}
+		const aLabels = toALabels(chunk);
+		for (let k = 0; k < chunk.length; k++) {
+			const start = spans[first + 3 * k];
+			const end = spans[first + 3 * k + 1];
+			const aLabel = aLabels[k];
+			if (aLabel === void 0) return fail("syntax.domain.label_invalid", start);
+			const bad = checkLabel(email, start, end, aLabel.length);
+			if (bad >= 0) return fail("syntax.domain.label_invalid", bad);
+			growth += aLabel.length - (end - start);
+			if (spans[first + 3 * k + 2] + (end - start) + growth > cap) return Infinity;
+		}
+		first = next;
+	}
+	return growth;
+}
+/**
+* The scan behind {@link scanDomain}, which leaves the U-labels it finds in
+* `uLabels`, as triples of start, end, and the domain's length before it,
+* unchecked but for their length.
+*/
+function scanLabels(email, at, rules, comments, uLabels) {
 	const end = email.length;
 	let domain = "";
 	let labels = 0;
@@ -1856,10 +2014,9 @@ function scanDomain(email, at, rules, comments) {
 	let edge = -1;
 	let trailing = comments.length;
 	let tld = "";
-	let growth = 0;
 	let i = at + 1;
 	while (i < end) {
-		const code = email.charCodeAt(i);
+		const code = codeAt(email, i);
 		const opensLiteral = code === 91 && rules.literals && labels === 0;
 		const ldh = inClass(code, rules.domain);
 		if (opensLiteral || ldh || rules.idn && nonAsciiAt(email, i, end) > 0) {
@@ -1872,20 +2029,18 @@ function scanDomain(email, at, rules, comments) {
 				literal = true;
 			} else {
 				next = ldh ? i + 1 : i;
-				while (next < end && inClass(email.charCodeAt(next), rules.domain)) next++;
+				while (next < end && inClass(codeAt(email, next), rules.domain)) next++;
 				const ascii = next;
 				if (rules.idn) next = skipUnicode(email, next, end, rules.domain);
-				let size = next - i;
 				if (next > ascii) {
-					const aLabel = toALabel(email.slice(i, next));
-					if (aLabel === void 0) return fail("syntax.domain.label_invalid", i);
-					size = aLabel.length;
-					growth += size - (next - i);
+					if (codePoints(email, i, next) > 63) return fail("syntax.domain.label_invalid", i);
+					uLabels.push(i, next, domain.length);
+				} else {
+					const bad = checkLabel(email, i, next, next - i);
+					if (bad >= 0) return fail("syntax.domain.label_invalid", bad);
 				}
-				const bad = checkLabel(email, i, next, size);
-				if (bad >= 0) return fail("syntax.domain.label_invalid", bad);
 			}
-			tld = unfold(email.slice(i, next));
+			tld = unfold(email, i, next);
 			domain += tld;
 			labels++;
 			afterLabel = true;
@@ -1924,7 +2079,7 @@ function scanDomain(email, at, rules, comments) {
 	if (labels === 0) return fail("syntax.domain.empty");
 	if (dot >= 0) return fail("syntax.domain.label_invalid", dot);
 	settle(comments, trailing, "after-domain");
-	const size = domain.length + growth;
+	const size = domain.length;
 	return literal || labels === 1 ? {
 		domain,
 		literal,
@@ -1944,7 +2099,7 @@ function skipUnicode(email, i, end, flag) {
 	let width = i < end ? nonAsciiAt(email, i, end) : 0;
 	while (width > 0) {
 		i += width;
-		while (i < end && inClass(email.charCodeAt(i), flag)) i++;
+		while (i < end && inClass(codeAt(email, i), flag)) i++;
 		width = i < end ? nonAsciiAt(email, i, end) : 0;
 	}
 	return i;
@@ -1955,9 +2110,9 @@ function skipUnicode(email, i, end, flag) {
 * a label over 63 characters, or -1.
 */
 function checkLabel(email, start, end, size) {
-	if (email.charCodeAt(start) === 45) return start;
+	if (codeAt(email, start) === 45) return start;
 	if (size > 63) return start;
-	return email.charCodeAt(end - 1) === 45 ? end - 1 : -1;
+	return codeAt(email, end - 1) === 45 ? end - 1 : -1;
 }
 /** Marks the comments from `from` on, which no word follows, as trailing. */
 function settle(comments, from, position) {
@@ -1966,18 +2121,23 @@ function settle(comments, from, position) {
 		if (comment.position.startsWith("inside")) comment.position = position;
 	}
 }
-/** Removes the CRLFs of folding whitespace, keeping the space or tab after. */
-function unfold(text) {
-	return text.includes("\r") ? text.replaceAll("\r\n", "") : text;
+const { indexOf, slice } = String.prototype;
+/**
+* `email` from `start` to `end`, without the CRLFs of folding whitespace,
+* keeping the space or tab after each.
+*/
+function unfold(email, start, end) {
+	const text = slice.call(email, start, end);
+	return indexOf.call(text, "\r") < 0 ? text : text.replaceAll("\r\n", "");
 }
 /**
 * Skips one character of folding whitespace: a space, a tab, or a CRLF with
 * a space or tab after it. A lone CR or LF breaks it.
 */
 function skipSpace(email, i, end) {
-	const code = email.charCodeAt(i);
+	const code = codeAt(email, i);
 	if (code === 32 || code === 9) return i + 1;
-	return code === 13 && i + 2 < end && email.charCodeAt(i + 1) === 10 && (email.charCodeAt(i + 2) === 32 || email.charCodeAt(i + 2) === 9) ? i + 2 : -1 - i;
+	return code === 13 && i + 2 < end && codeAt(email, i + 1) === 10 && (codeAt(email, i + 2) === 32 || codeAt(email, i + 2) === 9) ? i + 2 : -1 - i;
 }
 /** Whether a backslash may escape `code`: any ASCII with `obs`, else VCHAR and space. */
 function escapable(code, obs) {
@@ -1991,10 +2151,10 @@ function escapable(code, obs) {
 function skipQuoted(email, open, end, obs, unicode) {
 	let i = open + 1;
 	while (i < end) {
-		const code = email.charCodeAt(i);
+		const code = codeAt(email, i);
 		if (code === 34) return i + 1;
 		if (code === 92) {
-			if (!escapable(email.charCodeAt(i + 1), obs)) return -2 - i;
+			if (!escapable(codeAt(email, i + 1), obs)) return -2 - i;
 			i += 2;
 		} else if (obs && isWhitespace(code)) {
 			i = skipSpace(email, i, end);
@@ -2016,14 +2176,14 @@ function skipComment(email, open, end, unicode) {
 	let depth = 1;
 	let i = open + 1;
 	while (i < end) {
-		const code = email.charCodeAt(i);
+		const code = codeAt(email, i);
 		if (code === 40 || code === 41) {
 			depth += code === 40 ? 1 : -1;
 			i++;
 			if (depth === 0) return i;
 		} else if (code === 92) {
 			if (i + 1 >= end) break;
-			if (!escapable(email.charCodeAt(i + 1), true)) return -2 - i;
+			if (!escapable(codeAt(email, i + 1), true)) return -2 - i;
 			i += 2;
 		} else if (isWhitespace(code)) {
 			i = skipSpace(email, i, end);
@@ -2044,10 +2204,10 @@ function skipComment(email, open, end, unicode) {
 function skipLiteral(email, open, end) {
 	let i = open + 1;
 	while (i < end) {
-		const code = email.charCodeAt(i);
+		const code = codeAt(email, i);
 		if (code === 93) return i + 1;
 		if (code === 92) {
-			if (i + 1 >= end || !escapable(email.charCodeAt(i + 1), true)) return -1;
+			if (i + 1 >= end || !escapable(codeAt(email, i + 1), true)) return -1;
 			i += 2;
 		} else if (isWhitespace(code)) {
 			i = skipSpace(email, i, end);
@@ -2078,18 +2238,20 @@ function skipAddressLiteral(email, open, end) {
 * the first check it fails.
 *
 * @remarks
-* The local part is checked before the domain, each left to right, then the
-* lengths, then a dotless domain, then the TLD. `index`, where a failure has
-* one, points at the offending character.
+* Input longer than `maxLength` (512 UTF-16 code units by default) fails as
+* `syntax.address.too_long` before it's scanned. Otherwise the local part is
+* checked before the domain, each left to right, then the lengths, then a
+* dotless domain, then the TLD. `index`, where a failure has one, points at
+* the offending character.
 *
 * @example
 * ```ts
-* const result = parseAddress('ada.lovelace@example.co.uk');
-* if (result.ok) {
-*   result.value.tld; // 'uk'
-* } else {
-*   result.reason; // e.g. 'syntax.local.invalid_char'
-* }
+* import { parseAddress } from '@email-utils/validator-syntax';
+*
+* parseAddress('ada.lovelace@example.co.uk');
+* // => { ok: true, value: { local: 'ada.lovelace', tld: 'uk' } }
+* parseAddress('ada..lovelace@example.com');
+* // => { ok: false, reason: 'syntax.local.consecutive_dots', index: 4 }
 * ```
 *
 * @throws TypeError when `email` isn't a string, or `options` are malformed.
@@ -2102,9 +2264,11 @@ function parseAddress(email, options) {
 *
 * @example
 * ```ts
-* isValidSyntax('ada@example.com'); // true
-* isValidSyntax('"ada"@example.com'); // false
-* isValidSyntax('"ada"@example.com', { preset: 'rfc5321' }); // true
+* import { isValidSyntax } from '@email-utils/validator-syntax';
+*
+* isValidSyntax('ada@example.com'); // => true
+* isValidSyntax('"ada"@example.com'); // => false
+* isValidSyntax('"ada"@example.com', { preset: 'rfc5321' }); // => true
 * ```
 *
 * @throws TypeError when `email` isn't a string, or `options` are malformed.
@@ -2118,9 +2282,14 @@ function isValidSyntax(email, options) {
 *
 * @example
 * ```ts
+* import { createSyntaxValidator } from '@email-utils/validator-syntax';
+*
 * const strict = createSyntaxValidator({ preset: 'rfc5321' });
-* strict.parse('a b@example.com'); // { ok: false, reason: 'syntax.local.unquoted_space', … }
-* strict.isValid('"a b"@example.com'); // true
+* strict.parse('a b@example.com');
+* // => { ok: false, reason: 'syntax.local.unquoted_space', index: 1 }
+* strict.isValid('"a b"@example.com'); // => true
+* createSyntaxValidator({ preset: 'html5', allowComments: true });
+* // => throws TypeError
 * ```
 *
 * @throws TypeError when `options` are malformed.