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

package/dist/fixtures.cjs

@@ -1,13 +1,35 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _email_utils_validator_syntax = require("./index.cjs");
 //#region src/fixtures/types.ts
+/**
+* Every preset, in the order the support matrix's columns take.
+*
+* @example
+* ```ts
+* import { isValidSyntax } from '@email-utils/validator-syntax';
+* import { presets } from '@email-utils/validator-syntax/fixtures';
+*
+* presets.filter((preset) => isValidSyntax('ada@localhost', { preset }));
+* // => ['html5']
+* ```
+*/
 const presets = [
 	"practical",
 	"rfc5321",
 	"rfc5322",
 	"html5"
 ];
-/** The support matrix's rows, in order, with each feature's label. */
+/**
+* The support matrix's rows, in order, with each feature's label.
+*
+* @example
+* ```ts
+* import { syntaxFeatures } from '@email-utils/validator-syntax/fixtures';
+*
+* syntaxFeatures[0];
+* // => { feature: 'dot-atom', label: 'Letters, digits, and single dots' }
+* ```
+*/
 const syntaxFeatures = [
 	{
 		feature: "dot-atom",
@@ -136,6 +158,20 @@ function quotedLocal(rfc) {
 	};
 }
 const longLabel = "abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghikl";
+/**
+* Dominic Sayers' is_email tests, each tagged with its `id` in tests.xml.
+*
+* @example
+* ```ts
+* import { isemailFixtures } from '@email-utils/validator-syntax/fixtures';
+*
+* isemailFixtures.find((fixture) => fixture.isemail === 5);
+* // => {
+* //   address: 'test@io',
+* //   expected: { practical: { ok: false, reason: 'syntax.domain.no_dot' } },
+* // }
+* ```
+*/
 const isemailFixtures = [
 	{
 		isemail: 1,
@@ -1306,6 +1342,21 @@ function withUppercase(fixture) {
 		description: `${fixture.description}, uppercased`
 	}];
 }
+/**
+* Every address the 0.0.1 test suite checked, with what 0.0.1 returned.
+*
+* @example
+* ```ts
+* import { legacyFixtures } from '@email-utils/validator-syntax/fixtures';
+*
+* // The addresses v1's default preset judges differently from 0.0.1.
+* const flipped = legacyFixtures.filter(
+*   (fixture) => fixture.flipped !== undefined,
+* );
+* flipped.every((fixture) => fixture.legacy !== fixture.expected.practical.ok);
+* // => true
+* ```
+*/
 const legacyFixtures = [
 	...withUppercase({
 		address: "simple@example.com",
@@ -1781,6 +1832,24 @@ const legacyFixtures = [
 ];
 //#endregion
 //#region src/fixtures/rfc3696.ts
+/**
+* RFC 3696's examples, as corrected by its erratum 246.
+*
+* @example
+* ```ts
+* import { rfc3696Fixtures } from '@email-utils/validator-syntax/fixtures';
+*
+* // Printed as valid, but a backslash escape needs a quoted string.
+* rfc3696Fixtures
+*   .filter((fixture) => !fixture.expected.rfc5322.ok)
+*   .map((fixture) => fixture.address);
+* // => [
+* //   'Abc\\@def@example.com',
+* //   'Fred\\ Bloggs@example.com',
+* //   'Joe.\\\\Blow@example.com',
+* // ]
+* ```
+*/
 const rfc3696Fixtures = [
 	{
 		address: "Abc\\@def@example.com",
@@ -1863,6 +1932,22 @@ const rfc3696Fixtures = [
 ];
 //#endregion
 //#region src/fixtures/wikipedia.ts
+/**
+* The examples from Wikipedia's "Email address" article.
+*
+* @example
+* ```ts
+* import { wikipediaFixtures } from '@email-utils/validator-syntax/fixtures';
+*
+* wikipediaFixtures.find((fixture) => fixture.address === 'admin@example');
+* // => {
+* //   expected: {
+* //     practical: { ok: false, reason: 'syntax.domain.no_dot' },
+* //     html5: { ok: true },
+* //   },
+* // }
+* ```
+*/
 const wikipediaFixtures = [
 	{
 		address: "FirstName.LastName@EasierReading.org",
@@ -2000,8 +2085,9 @@ const wikipediaFixtures = [
 * string, comment, or literal left open runs to the end, taking any `@`
 * with it.
 *
-* The first failure wins, checked in this order: empty input; the split;
-* the local part, left to right, then its length; the domain, left to right,
+* The first failure wins, checked in this order: empty input; input longer
+* than `maxLength` (512 by default, which no fixture reaches); the split; the
+* local part, left to right, then its length; the domain, left to right,
 * then its length; the address length; a dotless domain; the TLD. Where a
 * failure has a position, `index` points at the first offending character
 * in the whole address: the `(` of a disallowed or unterminated comment,
@@ -2010,14 +2096,38 @@ const wikipediaFixtures = [
 *
 * @packageDocumentation
 */
-/** Every fixture from every source, each address once. */
+/**
+* Every fixture from every source, each address once.
+*
+* @example
+* ```ts
+* import { isValidSyntax } from '@email-utils/validator-syntax';
+* import { syntaxFixtures } from '@email-utils/validator-syntax/fixtures';
+*
+* syntaxFixtures.every(
+*   ({ address, expected }) =>
+*     isValidSyntax(address, { preset: 'rfc5321' }) === expected.rfc5321.ok,
+* ); // => true
+* ```
+*/
 const syntaxFixtures = [
 	...legacyFixtures,
 	...isemailFixtures,
 	...wikipediaFixtures,
 	...rfc3696Fixtures
 ];
-/** The docs' support matrix: one row per feature, one column per preset. */
+/**
+* The docs' support matrix: one row per feature, one column per preset.
+*
+* @example
+* ```ts
+* import { supportMatrix } from '@email-utils/validator-syntax/fixtures';
+*
+* const row = supportMatrix().find(({ feature }) => feature === 'quoted-local');
+* row?.support;
+* // => { practical: 'no', rfc5321: 'yes', rfc5322: 'yes', html5: 'no' }
+* ```
+*/
 function supportMatrix() {
 	return syntaxFeatures.map(({ feature, label }) => {
 		const fixtures = syntaxFixtures.filter((fixture) => fixture.feature === feature);
@@ -2050,9 +2160,16 @@ function supportMatrix() {
 *
 * @example
 * ```ts
-* const { valid, invalid } = previewSyntaxOptions({ checkTld: false });
-* valid.filter((entry) => entry.changed); // now accepted, e.g. example@s.example
-* previewSyntaxOptions({ preset: 'html5' }, ['ada@localhost']).valid; // [{ address: 'ada@localhost', changed: false }]
+* import { previewSyntaxOptions } from '@email-utils/validator-syntax/fixtures';
+*
+* const { valid } = previewSyntaxOptions({ checkTld: false });
+* valid.find((entry) => entry.address === 'example@s.example');
+* // => { changed: true }
+* previewSyntaxOptions({ preset: 'html5' }, ['ada@localhost', 'ada@example..com']);
+* // => {
+* //   valid: [{ address: 'ada@localhost', changed: false }],
+* //   invalid: [{ address: 'ada@example..com', reason: 'syntax.domain.label_invalid' }],
+* // }
 * ```
 *
 * @param addresses - The addresses to judge; `syntaxFixtures` by default.