@email-utils/sanitizer/fixtures
The API of the fixtures entry point.
Interfaces
InvalidSanitizerEntry
An input the configuration can't normalize, and why.
Properties
changed
changed: boolean;Whether the default options normalize it.
description?
optional description?: string;The fixture's description; absent for addresses you pass in.
input
input: string;message?
optional message?: string;reason
reason: "sanitizer.address.unparsable";SanitizerFixture
One corpus input, what the default options give for it, and, when its feature needs an option, what that option gives.
Properties
description
description: string;expected
expected: SanitizerExpected;The result with the default options.
input
input: string;The string passed to normalizeEmail, surrounding whitespace and all.
with?
optional with?: object;The result with the one option that turns the fixture's feature on, for
inputs the defaults reject or leave alone: comments, quotes, - tags,
and custom domains.
expected
expected: SanitizerExpected;options
options: NormalizeOptions;SanitizerPreview
The inputs split by whether the configuration normalizes them.
Properties
invalid
invalid: InvalidSanitizerEntry[];valid
valid: ValidSanitizerEntry[];ValidSanitizerEntry
An input the configuration normalizes, and the forms it gets.
Extends
Properties
address
address: string;The address to email: local-part case, dots, subaddress tag, and comments kept.
Valid in RFC 5322 headers such as To:.
Inherited from
changed
changed: boolean;Whether the default options give different forms, or reject it.
description?
optional description?: string;The fixture's description; absent for addresses you pass in.
envelope
envelope: string;address without comments: valid in the SMTP envelope (RFC 5321).
Inherited from
input
input: string;key
key: string;Uniqueness key: two inputs that reach the same mailbox get the same key.
Store and compare it; never send mail to it. Normalizing it again, with
the same options, gives it back, unless a domain alias lengthened it past
a tiny syntax.maxLength.
Inherited from
provider?
optional provider?: string;The provider whose rules built the key: the provider option, or detected from the domain.
Inherited from
Type Aliases
SanitizerExpected
type SanitizerExpected =
| {
address: string;
envelope: string;
key: string;
ok: true;
provider?: ProviderId;
}
| {
ok: false;
reason: ReasonCode;
};What normalizeEmail gives for a fixture's input, without the failure message.
Variables
sanitizerFixtures
const sanitizerFixtures: readonly SanitizerFixture[];The sanitizer corpus: one fixture per normalization rule, and the ways an input fails to parse, in that order.
Remarks
Run each fixture's input through your own keying and compare it with
expected, or with with.expected under with.options, to check it keys
addresses exactly as normalizeEmail does.
Example
import { sanitizerFixtures } from '@email-utils/sanitizer/fixtures';
const fixture = sanitizerFixtures.find(
({ input }) => input === 'Ada(work)@gmail.com',
);
fixture?.expected;
// => { ok: false, reason: 'sanitizer.address.unparsable' }
fixture?.with;
// => {
// options: { syntax: { allowComments: true } },
// expected: { ok: true, key: 'ada@gmail.com', envelope: 'Ada@gmail.com' },
// }Functions
previewSanitizerOptions()
function previewSanitizerOptions(options?, addresses?): SanitizerPreview;Runs addresses through createSanitizer(options) and splits them into
the ones it normalizes, with their forms, and the ones it can't, each list
in input order.
Parameters
| Parameter | Type | Description |
|---|---|---|
options? | NormalizeOptions | - |
addresses? | readonly string[] | The inputs to normalize; the corpus's by default. |
Returns
Remarks
changed marks the inputs the options move: those the default options
would reject, accept, or key differently. With no options, nothing is
changed. The corpus inputs are judged by options alone; a fixture's
with isn't applied.
Example
import { previewSanitizerOptions } from '@email-utils/sanitizer/fixtures';
previewSanitizerOptions({ provider: 'google-workspace' }, [
'A.da+news@example.com',
'ada@',
]);
// => {
// valid: [
// {
// input: 'A.da+news@example.com',
// key: 'a.da@example.com',
// changed: true,
// },
// ],
// invalid: [
// {
// input: 'ada@',
// reason: 'sanitizer.address.unparsable',
// changed: false,
// },
// ],
// }
// With no addresses, it previews the corpus: the comment fixtures now pass.
previewSanitizerOptions({ syntax: { allowComments: true } })
.valid.filter((entry) => entry.changed)
.map((entry) => entry.input);
// => ['Ada(work)@gmail.com', '(home)ada@(mx)example.com']Throws
TypeError when options are malformed or name an option that
doesn't exist, or addresses isn't an array of strings.