@portable/idna

Functions

`Idna.toAscii`

Converts a domain name to the ASCII form that DNS and URL use, with Punycode xn-- labels for non-ASCII labels. Follows UTS #46 and the URL Standard's domain parser, so the result equals new URL('http://' + domain).hostname for any domain that doesn't end in a number.

function toAscii(domain: string, options: toAscii.Options = {}): string;

Option	Type	Default	Description
`strict`	`boolean`	`false`	Apply the hostname rules of STD 3 and the DNS length limits: only `a-z`, `0-9` and `-` in a label, no `-` at either end of a label or in its third and fourth positions, and at most 63 characters in a label and 253 in the name. This is the URL Standard's `beStrict`.

Throws

InvalidInputError if the domain isn't valid.

import * as Idna from '@portable/idna';
 
Idna.toAscii('Bücher.example'); // 'xn--bcher-kva.example'

`Idna.toUnicode`

Converts a domain name to Unicode for display, decoding its Punycode xn-- labels. Follows UTS #46 ToUnicode with the URL Standard's settings, and also maps and normalizes Unicode input, so toUnicode('xn--bcher-kva.example') and toUnicode('BÜCHER.example') agree.

function toUnicode(
  domain: string,
  options: toUnicode.Options = {},
): string;

Option	Type	Default	Description
`strict`	`boolean`	`false`	Apply the hostname rules of STD 3: only `a-z`, `0-9` and `-` in a label, and no `-` at either end of a label or in its third and fourth positions.

Throws

InvalidInputError if the domain isn't valid, such as a label that isn't valid Punycode or decodes to characters IDNA doesn't allow.

import * as Idna from '@portable/idna';
 
Idna.toUnicode(new URL('https://xn--bcher-kva.example/').hostname); // 'bücher.example'

Errors

`Idna.InvalidInputError`

Thrown when a domain name breaks the rules of UTS #46.

class InvalidInputError extends Errors.InvalidInputError {
  readonly kind: string;
}

import * as Idna from '@portable/idna';
 
try {
  Idna.toUnicode('www.xn--b.com');
} catch (error) {
  if (error instanceof Idna.InvalidInputError) {
    console.log(error.message);
  }
}