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

package/dist/fixtures.d.cts

@@ -1,9 +1,26 @@
-import { i as SyntaxOptions, t as ReasonCode } from "./result-BZjmlevS.cjs";
+import { i as SyntaxOptions, t as ReasonCode } from "./result-CNbJ54oT.cjs";
 //#region src/fixtures/types.d.ts
+/** A preset's name: the same union as the root entry's `Preset`. */
 type Preset = "practical" | "rfc5321" | "rfc5322" | "html5";
+/**
+ * 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']
+ * ```
+ */
 export declare const presets: readonly Preset[];
 /** The `syntax.*` codes from the reason-code catalogue (meta docs/api/reason-codes.md). */
 type SyntaxReasonCode = ReasonCode;
+/**
+ * A fixture's result under one preset: the `ok`, `reason`, and `index` of
+ * what `parseAddress` returns, without the value or message.
+ */
 type Expected = {
   ok: true;
 } | {
@@ -17,11 +34,22 @@ type Expected = {
  * which presets accept the tagged fixtures gives the matrix.
  */
 type SyntaxFeature = "dot-atom" | "atext-specials" | "route-chars" | "misplaced-dots" | "long-local" | "quoted-local" | "quoted-pair" | "obs-local" | "comments" | "fws" | "obs-control" | "ipv4-literal" | "ipv6-literal" | "general-literal" | "dotless-domain" | "unknown-tld";
-/** 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' }
+ * ```
+ */
 export declare const syntaxFeatures: readonly {
   feature: SyntaxFeature;
   label: string;
 }[];
+/** An address, and what each preset makes of it. */
 interface SyntaxFixture {
   address: string;
   description: string;
@@ -30,6 +58,7 @@ interface SyntaxFixture {
   /** The support-matrix row this fixture is a well-formed example of. */
   feature?: SyntaxFeature;
 }
+/** A fixture from the 0.0.1 test suite, with what 0.0.1 made of it. */
 interface LegacyFixture extends SyntaxFixture {
   /** What 0.0.1's `validate()` returned with its default config. */
   legacy: boolean;
@@ -40,27 +69,106 @@ interface LegacyFixture extends SyntaxFixture {
    */
   flipped?: string;
 }
+/** A fixture from isemail's test set. */
 interface IsemailFixture extends SyntaxFixture {
   /** The test's `id` in isemail's tests.xml. */
   isemail: number;
 }
 //#endregion
 //#region src/fixtures/isemail.d.ts
+/**
+ * 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' } },
+ * // }
+ * ```
+ */
 export declare const isemailFixtures: readonly IsemailFixture[];
 //#endregion
 //#region src/fixtures/legacy.d.ts
+/**
+ * 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
+ * ```
+ */
 export declare const legacyFixtures: readonly LegacyFixture[];
 //#endregion
 //#region src/fixtures/rfc3696.d.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',
+ * // ]
+ * ```
+ */
 export declare const rfc3696Fixtures: readonly SyntaxFixture[];
 //#endregion
 //#region src/fixtures/wikipedia.d.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 },
+ * //   },
+ * // }
+ * ```
+ */
 export declare const wikipediaFixtures: readonly SyntaxFixture[];
 //#endregion
 //#region src/fixtures/index.d.ts
-/** 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
+ * ```
+ */
 export declare const syntaxFixtures: readonly SyntaxFixture[];
+/** Whether a preset accepts all, some, or none of a feature's fixtures. */
 export type Support = "yes" | "partial" | "no";
+/** A row of {@link supportMatrix}: one feature, and each preset's support. */
 export interface SupportRow {
   feature: SyntaxFeature;
   label: string;
@@ -69,7 +177,18 @@ export interface SupportRow {
   /** The feature's fixtures, for examples. */
   fixtures: readonly SyntaxFixture[];
 }
-/** 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' }
+ * ```
+ */
 export declare function supportMatrix(): SupportRow[];
 /** An address the configuration accepts. */
 export interface ValidPreviewEntry {
@@ -106,9 +225,16 @@ export interface SyntaxPreview {
  *
  * @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.

package/dist/fixtures.d.mts

@@ -1,9 +1,26 @@
-import { i as SyntaxOptions, t as ReasonCode } from "./result-BZjmlevS.mjs";
+import { i as SyntaxOptions, t as ReasonCode } from "./result-CNbJ54oT.mjs";
 //#region src/fixtures/types.d.ts
+/** A preset's name: the same union as the root entry's `Preset`. */
 type Preset = "practical" | "rfc5321" | "rfc5322" | "html5";
+/**
+ * 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']
+ * ```
+ */
 export declare const presets: readonly Preset[];
 /** The `syntax.*` codes from the reason-code catalogue (meta docs/api/reason-codes.md). */
 type SyntaxReasonCode = ReasonCode;
+/**
+ * A fixture's result under one preset: the `ok`, `reason`, and `index` of
+ * what `parseAddress` returns, without the value or message.
+ */
 type Expected = {
   ok: true;
 } | {
@@ -17,11 +34,22 @@ type Expected = {
  * which presets accept the tagged fixtures gives the matrix.
  */
 type SyntaxFeature = "dot-atom" | "atext-specials" | "route-chars" | "misplaced-dots" | "long-local" | "quoted-local" | "quoted-pair" | "obs-local" | "comments" | "fws" | "obs-control" | "ipv4-literal" | "ipv6-literal" | "general-literal" | "dotless-domain" | "unknown-tld";
-/** 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' }
+ * ```
+ */
 export declare const syntaxFeatures: readonly {
   feature: SyntaxFeature;
   label: string;
 }[];
+/** An address, and what each preset makes of it. */
 interface SyntaxFixture {
   address: string;
   description: string;
@@ -30,6 +58,7 @@ interface SyntaxFixture {
   /** The support-matrix row this fixture is a well-formed example of. */
   feature?: SyntaxFeature;
 }
+/** A fixture from the 0.0.1 test suite, with what 0.0.1 made of it. */
 interface LegacyFixture extends SyntaxFixture {
   /** What 0.0.1's `validate()` returned with its default config. */
   legacy: boolean;
@@ -40,27 +69,106 @@ interface LegacyFixture extends SyntaxFixture {
    */
   flipped?: string;
 }
+/** A fixture from isemail's test set. */
 interface IsemailFixture extends SyntaxFixture {
   /** The test's `id` in isemail's tests.xml. */
   isemail: number;
 }
 //#endregion
 //#region src/fixtures/isemail.d.ts
+/**
+ * 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' } },
+ * // }
+ * ```
+ */
 export declare const isemailFixtures: readonly IsemailFixture[];
 //#endregion
 //#region src/fixtures/legacy.d.ts
+/**
+ * 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
+ * ```
+ */
 export declare const legacyFixtures: readonly LegacyFixture[];
 //#endregion
 //#region src/fixtures/rfc3696.d.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',
+ * // ]
+ * ```
+ */
 export declare const rfc3696Fixtures: readonly SyntaxFixture[];
 //#endregion
 //#region src/fixtures/wikipedia.d.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 },
+ * //   },
+ * // }
+ * ```
+ */
 export declare const wikipediaFixtures: readonly SyntaxFixture[];
 //#endregion
 //#region src/fixtures/index.d.ts
-/** 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
+ * ```
+ */
 export declare const syntaxFixtures: readonly SyntaxFixture[];
+/** Whether a preset accepts all, some, or none of a feature's fixtures. */
 export type Support = "yes" | "partial" | "no";
+/** A row of {@link supportMatrix}: one feature, and each preset's support. */
 export interface SupportRow {
   feature: SyntaxFeature;
   label: string;
@@ -69,7 +177,18 @@ export interface SupportRow {
   /** The feature's fixtures, for examples. */
   fixtures: readonly SyntaxFixture[];
 }
-/** 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' }
+ * ```
+ */
 export declare function supportMatrix(): SupportRow[];
 /** An address the configuration accepts. */
 export interface ValidPreviewEntry {
@@ -106,9 +225,16 @@ export interface SyntaxPreview {
  *
  * @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.

package/dist/fixtures.mjs

@@ -1,12 +1,34 @@
 import { createSyntaxValidator } from "./index.mjs";
 //#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",
@@ -135,6 +157,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,
@@ -1305,6 +1341,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",
@@ -1780,6 +1831,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",
@@ -1862,6 +1931,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",
@@ -1999,8 +2084,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,
@@ -2009,14 +2095,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);
@@ -2049,9 +2159,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.