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

package/dist/fixtures.d.mts

@@ -0,0 +1,247 @@
+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;
+} | {
+  ok: false;
+  reason: SyntaxReasonCode;
+  index?: number;
+};
+/**
+ * The address features the support matrix has a row for. A fixture is tagged
+ * with one only when it's a well-formed example of that feature, so counting
+ * 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.
+ *
+ * @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;
+  /** The result with each preset's default options. */
+  expected: Record<Preset, Expected>;
+  /** 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;
+  /**
+   * Why v1's default preset (`practical`) disagrees with `legacy`: the 0.0.1
+   * bug it was, or the v1 rule that changed. Required exactly when they
+   * disagree.
+   */
+  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.
+ *
+ * @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;
+  /** Whether the preset accepts all, some, or none of the feature's fixtures. */
+  support: Record<Preset, Support>;
+  /** The feature's fixtures, for examples. */
+  fixtures: readonly SyntaxFixture[];
+}
+/**
+ * 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 {
+  address: string;
+  /** The fixture's description; absent for addresses you pass in. */
+  description?: string;
+  /** Whether the preset alone, without the overrides, would reject it. */
+  changed: boolean;
+}
+/** An address the configuration rejects, and the first check it fails. */
+export interface InvalidPreviewEntry {
+  address: string;
+  /** The fixture's description; absent for addresses you pass in. */
+  description?: string;
+  reason: ReasonCode;
+  message?: string;
+  index?: number;
+  /** Whether the preset alone, without the overrides, would accept it. */
+  changed: boolean;
+}
+/** The addresses split by whether the configuration accepts them. */
+export interface SyntaxPreview {
+  valid: ValidPreviewEntry[];
+  invalid: InvalidPreviewEntry[];
+}
+/**
+ * Runs `addresses` through `createSyntaxValidator(options)` and splits them
+ * into the ones it accepts and the ones it rejects, each list in input
+ * order.
+ *
+ * @remarks
+ * `changed` marks the addresses the overrides move: those the preset alone
+ * would judge the other way. With no overrides, nothing is changed.
+ *
+ * @example
+ * ```ts
+ * 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.
+ * @throws TypeError when `options` are malformed, or `addresses` isn't an
+ * array of strings.
+ */
+export declare function previewSyntaxOptions(options?: SyntaxOptions, addresses?: readonly string[]): SyntaxPreview;
+//#endregion
+export type { Expected, IsemailFixture, LegacyFixture, Preset, SyntaxFeature, SyntaxFixture, SyntaxReasonCode };
+//# sourceMappingURL=fixtures.d.mts.map