Domain Normalizer

Build a utility that normalizes domain names or email addresses to either ASCII or Unicode form while respecting email-local-part boundaries.

Capabilities

Normalizes domain separators to dots before conversion

• Input ["例子｡测试"] in ASCII mode yields ["xn--fsqu00a.xn--0zwm56d"] @test

Preserves email local parts while converting domain segments

• Input ["user+tag@bücher。例．com"] in ASCII mode returns ["user+tag@xn--bcher-kva.xn--fsq.com"], leaving text before @ unchanged @test
• ASCII-only inputs such as "support@example.com" and "example.com" remain unchanged in ASCII mode @test

Decodes punycoded domains to Unicode on request

• Input ["user@xn--bcher-kva.xn--fsq.com"] in Unicode mode returns ["user@bücher.例.com"], converting only punycoded labels and leaving plain ASCII untouched @test

Implementation

@generates

API

export type NormalizationMode = 'ascii' | 'unicode';

/**
 * Normalizes the domain component of domain names or email addresses.
 * - Accepts plain domains or full email addresses.
 * - Normalizes IDNA separator variants in domain labels before conversion.
 * - Only transforms the domain portion; the email local part is returned verbatim.
 * - When mode is 'ascii' (default), non-ASCII domain labels are converted to Punycode while ASCII labels are untouched.
 * - When mode is 'unicode', punycoded labels (`xn--` prefix) are decoded while plain ASCII labels are untouched.
 */
export function normalizeAddresses(
  inputs: string[],
  mode?: NormalizationMode
): string[];

Dependencies { .dependencies }

punycode { .dependency }

Provides IDNA-safe domain conversion and separator handling.