@email-utils/validator-syntax/fixtures
The API of the fixtures entry point.
Interfaces
InvalidPreviewEntry
An address the configuration rejects, and the first check it fails.
Properties
address
address: string;changed
changed: boolean;Whether the preset alone, without the overrides, would accept it.
description?
optional description?: string;The fixture's description; absent for addresses you pass in.
index?
optional index?: number;message?
optional message?: string;reason
reason: ReasonCode;IsemailFixture
A fixture from isemail's test set.
Extends
Properties
address
address: string;Inherited from
description
description: string;Inherited from
expected
expected: Record<Preset, Expected>;The result with each preset's default options.
Inherited from
feature?
optional feature?: SyntaxFeature;The support-matrix row this fixture is a well-formed example of.
Inherited from
isemail
isemail: number;The test's id in isemail's tests.xml.
LegacyFixture
A fixture from the 0.0.1 test suite, with what 0.0.1 made of it.
Extends
Properties
address
address: string;Inherited from
description
description: string;Inherited from
expected
expected: Record<Preset, Expected>;The result with each preset's default options.
Inherited from
feature?
optional feature?: SyntaxFeature;The support-matrix row this fixture is a well-formed example of.
Inherited from
flipped?
optional flipped?: string;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.
legacy
legacy: boolean;What 0.0.1's validate() returned with its default config.
SupportRow
A row of supportMatrix: one feature, and each preset's support.
Properties
feature
feature: SyntaxFeature;fixtures
fixtures: readonly SyntaxFixture[];The feature's fixtures, for examples.
label
label: string;support
support: Record<Preset, Support>;Whether the preset accepts all, some, or none of the feature's fixtures.
SyntaxFixture
An address, and what each preset makes of it.
Extended by
Properties
address
address: string;description
description: string;expected
expected: Record<Preset, Expected>;The result with each preset's default options.
feature?
optional feature?: SyntaxFeature;The support-matrix row this fixture is a well-formed example of.
SyntaxPreview
The addresses split by whether the configuration accepts them.
Properties
invalid
invalid: InvalidPreviewEntry[];valid
valid: ValidPreviewEntry[];ValidPreviewEntry
An address the configuration accepts.
Properties
address
address: string;changed
changed: boolean;Whether the preset alone, without the overrides, would reject it.
description?
optional description?: string;The fixture's description; absent for addresses you pass in.
Type Aliases
Expected
type Expected =
| {
ok: true;
}
| {
index?: number;
ok: false;
reason: SyntaxReasonCode;
};A fixture's result under one preset: the ok, reason, and index of
what parseAddress returns, without the value or message.
Preset
type Preset = "practical" | "rfc5321" | "rfc5322" | "html5";A preset's name: the same union as the root entry's Preset.
Support
type Support = "yes" | "partial" | "no";Whether a preset accepts all, some, or none of a feature's fixtures.
SyntaxFeature
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 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.
SyntaxReasonCode
type SyntaxReasonCode = ReasonCode;The syntax.* codes from the reason-code catalogue
(https://email-utils.github.io/meta/docs/reference/reason-codes#validator-syntax).
Variables
isemailFixtures
const isemailFixtures: readonly IsemailFixture[];Dominic Sayers' is_email tests, each tagged with its id in tests.xml.
Example
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' } },
// }legacyFixtures
const legacyFixtures: readonly LegacyFixture[];Every address the 0.0.1 test suite checked, with what 0.0.1 returned.
Example
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);
// => truepresets
const presets: readonly Preset[];Every preset, in the order the support matrix's columns take.
Example
import { isValidSyntax } from '@email-utils/validator-syntax';
import { presets } from '@email-utils/validator-syntax/fixtures';
presets.filter((preset) => isValidSyntax('ada@localhost', { preset }));
// => ['html5']rfc3696Fixtures
const rfc3696Fixtures: readonly SyntaxFixture[];RFC 3696's examples, as corrected by its erratum 246.
Example
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',
// ]syntaxFeatures
const syntaxFeatures: readonly object[];The support matrix's rows, in order, with each feature's label.
Example
import { syntaxFeatures } from '@email-utils/validator-syntax/fixtures';
syntaxFeatures[0];
// => { feature: 'dot-atom', label: 'Letters, digits, and single dots' }syntaxFixtures
const syntaxFixtures: readonly SyntaxFixture[];Every fixture from every source, each address once.
Example
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,
); // => truewikipediaFixtures
const wikipediaFixtures: readonly SyntaxFixture[];The examples from Wikipedia's "Email address" article.
Example
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 },
// },
// }Functions
previewSyntaxOptions()
function previewSyntaxOptions(options?, addresses?): SyntaxPreview;Runs addresses through createSyntaxValidator(options) and splits them
into the ones it accepts and the ones it rejects, each list in input
order.
Parameters
| Parameter | Type | Description |
|---|---|---|
options? | SyntaxOptions | - |
addresses? | readonly string[] | The addresses to judge; syntaxFixtures by default. |
Returns
Remarks
changed marks the addresses the overrides move: those the preset alone
would judge the other way. With no overrides, nothing is changed.
Example
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' }],
// }Throws
TypeError when options are malformed, or addresses isn't an
array of strings.
supportMatrix()
function supportMatrix(): SupportRow[];The docs' support matrix: one row per feature, one column per preset.
Returns
Example
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' }