Punycode

Convert between Unicode and ASCII using the Punycode encoding scheme for internationalized domain names

Deprecated since v7.0.0 - This module is pending removal in a future major version of Node.js.

The version of the punycode module bundled in Node.js is being deprecated. Users currently depending on the punycode module should switch to using the userland-provided Punycode.js module instead. For punycode-based URL encoding, see url.domainToASCII() or the WHATWG URL API.

Overview

The punycode module is a bundled version of the Punycode.js module. It can be accessed using:

const punycode = require('node:punycode');

Punycode is a character encoding scheme defined by RFC 3492 that is primarily intended for use in Internationalized Domain Names. Because host names in URLs are limited to ASCII characters only, Domain Names that contain non-ASCII characters must be converted into ASCII using the Punycode scheme.

For instance, the Japanese character that translates into the English word 'example' is '例'. The Internationalized Domain Name '例.com' (equivalent to 'example.com') is represented by Punycode as the ASCII string 'xn--fsq.com'.

Methods

punycode.decode(string)

Converts a Punycode string of ASCII-only characters to the equivalent string of Unicode codepoints.

Parameters:

• string (string) - The Punycode string to decode

Returns: String of Unicode codepoints

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

punycode.encode(string)

Converts a string of Unicode codepoints to a Punycode string of ASCII-only characters.

Parameters:

• string (string) - The Unicode string to encode

Returns: Punycode string

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

punycode.toASCII(domain)

Converts a Unicode string representing an Internationalized Domain Name to Punycode. Only the non-ASCII parts of the domain name will be converted. Calling punycode.toASCII() on a string that already only contains ASCII characters will have no effect.

Parameters:

• domain (string) - The domain name to convert

Returns: ASCII representation of the domain

punycode.toASCII('mañana.com');  // 'xn--maana-pta.com'
punycode.toASCII('☃-⌘.com');   // 'xn----dqo34k.com'
punycode.toASCII('example.com'); // 'example.com'

punycode.toUnicode(domain)

Converts a string representing a domain name containing Punycode encoded characters into Unicode. Only the Punycode encoded parts of the domain name are converted.

Parameters:

• domain (string) - The Punycode domain name to convert

Returns: Unicode representation of the domain

punycode.toUnicode('xn--maana-pta.com'); // 'mañana.com'
punycode.toUnicode('xn----dqo34k.com');  // '☃-⌘.com'
punycode.toUnicode('example.com');       // 'example.com'

UCS-2 Encoding

punycode.ucs2.decode(string)

Returns an array containing the numeric codepoint values of each Unicode symbol in the string.

Parameters:

• string (string) - The string to decode

Returns: Array of numeric codepoint values

punycode.ucs2.decode('abc'); // [0x61, 0x62, 0x63]
// surrogate pair for U+1D306 tetragram for centre:
punycode.ucs2.decode('\uD834\uDF06'); // [0x1D306]

punycode.ucs2.encode(codePoints)

Returns a string based on an array of numeric code point values.

Parameters:

• codePoints (integer[]) - Array of numeric code points

Returns: String representation

punycode.ucs2.encode([0x61, 0x62, 0x63]); // 'abc'
punycode.ucs2.encode([0x1D306]); // '\uD834\uDF06'

Properties

punycode.version

Returns a string identifying the current Punycode.js version number.

Type: string