NodeJS Punycode: A Complete Guide

Punycode is an encoding syntax representing Unicode using ASCII characters. Punycode can be helpful in transforming the UTF-8 string to ASCII.

UTF-8 is a standard universal encoding used worldwide, it is used to process, store and interchange text data on the internet and supports every language, and represents more than 1,40,000 characters whereas ASCII stands for American standard code for information interchange which is specially created for electronic computers and ASCII can only represent 128 characters.

Most strings are encoded in UTF-8, but the hostname can only contain the ASCII string of characters.

A hostname is the unique label of a device connected to the internet used to identify the device in various places such as requesting a resource from a website or WWW(World Wide Web). This hostname can be a single word or a group of many words containing at least one numeric key representing the network address association.

For the hostname, it is required to somehow convert or encode the UTF-8 encoding to ASCII which we can do using the Node.js Punycode module.

What is the NodeJS Punycode module?

Punycode Module is a built-in module in Node.js that gives many methods like encode and decode which is used to encode a string of Unicode (UTF-8) into a Punycode string of ASCII and then decode it to the original string of Unicode symbols.

For using Punycode encoding/decoding methods, it is required to import the Punycode module using the below statement.

Syntax:

const punycode = require('punycode');

Methods of NodeJS Punycode module

Let’s get right into the NodeJS Punycode module now.

1. encode()

It takes a string of Unicode symbols as an argument and returns it by converting it into a Punycode string of ASCII.

Syntax:

punycode.encode(string)

where a string is a group of any character, word, or symbol of Unicode.

Example:

const punycode = require('punycode');
const  result = punycode.encode('Hello⌘World!');  
console.log(result);

Here we are passing a string “Hello⌘World” which contains a non-ASCII symbol.

Output:

HelloWorld!-r00g

2. decode()

It takes a Punycode string of ASCII as an argument and returns it by converting it into a string of Unicode symbols.

Syntax:

punycode.decode(string)

where a string is a Punycode string.

Example:

const punycode = require('punycode');
const result = punycode.decode('HelloWorld!-r00g');  
console.log(result);

Here we are passing a string of Punycode, which we get in the above example to get the original string of Unicode.

Output:

Hello⌘World!

3. toASCII()

This method takes the domain name as an argument and converts the non-ASCII part of it into the Punycode of ASCII symbols.

Syntax:

punycode.toASCII(domain)

where the domain is the domain that needs to convert into Punycode.

Example:

const punycode = require('punycode');
const result = punycode.toASCII('rupee₹.com');
console.log(result);

Here we are passing a domain in which a non-ASCII symbol is ₹ which is converted into a Punycode of ASCII symbols.

Output:

xn--rupee-jo4b.com

4. toUnicode()

This method is opposite to the method toASCII(). This method takes a domain name in the Punycode string of ASCII symbols and converts the Punycode part into Unicode.

Syntax:

punycode.toUnicode(domain)

where the domain is the domain that needs to convert into Unicode.

Example:

const punycode = require('punycode');
const result = punycode.toUnicode('xn--rupee-jo4b.com');
console.log(result);

Here we are passing a domain of Punycode, which we get in the above example to get the original domain.

Output:

rupee₹.com

Summary

The hostname is not supported for non-ASCII symbols, so it is required to convert any string containing a non-ASCII symbol into Punycode, which only contains ASCII symbols.

For this conversion, we can use the Node.js Punycode module, which provides various methods such as encode (to convert Unicode into Punycode), decode (to convert Punycode into Unicode), toASCII (to convert the non-ASCII part of a domain into ASCII code), and toUnicode (to convert a Punycode part of a domain into Unicode).

We hope this tutorial helps you to understand the concept of Punycode, the Punycode module, and its methods in Node.js.