punycode-esm

ESM and TypeScript port of the punycode.js library.

Contents

• Install
• Example
• Usage
• API
  • encode
  • decode
  • toASCII
  • toUnicode
  • ucs2Decode
  • ucs2Encode
• Credit

Install

npm i punycode-esm

Example

import { toASCII, toUnicode } from 'punycode-esm';

// encode domain names
toASCII('mañana.com');  // 'xn--maana-pta.com'
toASCII('☃-⌘.com');    // 'xn----dqo34k.com'

// decode domain names
toUnicode('xn--maana-pta.com'); // 'mañana.com'
toUnicode('xn----dqo34k.com');  // '☃-⌘.com'

Usage

punycode-esm is an ESM module. It must be imported. To load from a CJS module, use dynamic import: const { encode } = await import('punycode-esm').

Functions throw RangeError for malformed Punycode: decode and toUnicode for input that is not ASCII (Invalid input), is not valid Punycode, or needs wider integers than JavaScript numbers hold (Overflow: input needs wider integers to process); encode and toASCII for the overflow case only. toASCII and toUnicode only convert labels, and do none of the other IDNA processing: no case folding, no Unicode normalization and no length checks. They split on . and the other full-stop characters 。, ． and ｡ (all written as . in the result), and only recognise the lowercase xn-- prefix.

API

encode(string)

Converts a string of Unicode symbols (a single domain label) to a Punycode string of ASCII-only symbols.

Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | string | string | — | Required. A Unicode domain label (no dots). |

Returns string — the Punycode-encoded ASCII label.

encode('mañana'); // 'maana-pta'
encode('☃-⌘');   // '--dqo34k'

decode(string)

Converts a Punycode string of ASCII-only symbols (a single domain label) to a string of Unicode symbols.

Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | string | string | — | Required. A Punycode-encoded ASCII label (no dots). |

Returns string — the decoded Unicode label.

decode('maana-pta'); // 'mañana'
decode('--dqo34k');  // '☃-⌘'

toASCII(string)

Converts a Unicode domain name or email address to its Punycode (ASCII) representation. Only non-ASCII labels are converted; already-ASCII labels are left unchanged.

Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | string | string | — | Required. A Unicode domain name or email address. |

Returns string — the ASCII-compatible encoding of the domain or email.

toASCII('mañana.com');                     // 'xn--maana-pta.com'
toASCII('☃-⌘.com');                       // 'xn----dqo34k.com'
toASCII('джумла@джpумлатест.bрфa');        // 'джумла@xn--p-8sbkgc5ag7bhce.xn--ba-lmcq'

toUnicode(string)

Converts a Punycode domain name or email address to Unicode. Only Punycode-encoded labels (prefixed with xn--) are converted; others are left unchanged.

Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | string | string | — | Required. A Punycode domain name or email address. |

Returns string — the Unicode representation of the domain or email.

toUnicode('xn--maana-pta.com');                          // 'mañana.com'
toUnicode('xn----dqo34k.com');                           // '☃-⌘.com'
toUnicode('джумла@xn--p-8sbkgc5ag7bhce.xn--ba-lmcq');   // 'джумла@джpумлатест.bрфa'

ucs2Decode(string)

Creates an array of Unicode code point values from a string. Surrogate pairs (as used internally by JavaScript's UCS-2 encoding) are combined into a single code point, matching UTF-16 semantics.

Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | string | string | — | Required. A UCS-2 encoded string. |

Returns number[] — array of Unicode code point integers.

ucs2Decode('abc');           // [0x61, 0x62, 0x63]
ucs2Decode('\uD834\uDF06');  // [0x1D306]

ucs2Encode(codePoints)

Creates a string from an array of Unicode code point values.

Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | codePoints | readonly number[] | — | Required. Array of Unicode code point integers. |

Returns string — the UCS-2 encoded string.

ucs2Encode([0x61, 0x62, 0x63]); // 'abc'
ucs2Encode([0x1D306]);          // '\uD834\uDF06'

Credit

This is a direct ESM/TypeScript port of punycode.js by Mathias Bynens. The logic is identical; this package exists for compatibility with TypeScript moduleResolution: nodenext and pure-ESM projects. Logic is in sync with punycode v2.3.1.

• Original npm package: punycode
• Original GitHub repository: mathiasbynens/punycode.js