0
# Punycode
1

2
Punycode is a robust converter that fully complies to RFC 3492 and RFC 5891, and works on nearly all JavaScript platforms. It provides encoding and decoding functionality for internationalized domain names and email addresses, converting between Unicode and ASCII representations.
3

4
## Package Information
5

6
- **Package Name**: punycode
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install punycode`
10
- **Build Output**: CommonJS (`punycode.js`) and ES modules (`punycode.es6.js`, generated via build script)
11

12
## Core Imports
13

14
**CommonJS (recommended):**
15

16
```javascript
17
const punycode = require('punycode/');
18
```
19

20
**ES Modules:**
21

22
```javascript
23
// Default import (entire punycode object)
24
import punycode from 'punycode/punycode.es6.js';
25

26
// Named imports (individual functions) 
27
import { decode, encode, toASCII, toUnicode, ucs2decode, ucs2encode } from 'punycode/punycode.es6.js';
28
```
29

30
**Note**: Use the trailing slash (`punycode/`) to import the userland module instead of Node.js's deprecated core module.
31

32
## Basic Usage
33

34
**CommonJS:**
35

36
```javascript
37
const punycode = require('punycode/');
38

39
// Convert Unicode to ASCII (Punycode)
40
const encoded = punycode.encode('mañana');  // 'maana-pta'
41
const decoded = punycode.decode('maana-pta');  // 'mañana'
42

43
// Convert domain names
44
const unicodeDomain = punycode.toUnicode('xn--maana-pta.com');  // 'mañana.com'
45
const asciiDomain = punycode.toASCII('mañana.com');  // 'xn--maana-pta.com'
46

47
// Work with email addresses
48
const unicodeEmail = punycode.toUnicode('джумла@xn--p-8sbkgc5ag7bhce.xn--ba-lmcq');
49
const asciiEmail = punycode.toASCII('джумла@джpумлатест.bрфa');
50

51
// Convert between strings and code points
52
const codePoints = punycode.ucs2.decode('abc');  // [0x61, 0x62, 0x63]
53
const string = punycode.ucs2.encode([0x61, 0x62, 0x63]);  // 'abc'
54
```
55

56
**ES Modules (using named imports):**
57

58
```javascript
59
import { encode, decode, toUnicode, toASCII, ucs2decode, ucs2encode } from 'punycode/punycode.es6.js';
60

61
// Convert Unicode to ASCII (Punycode)
62
const encoded = encode('mañana');  // 'maana-pta'
63
const decoded = decode('maana-pta');  // 'mañana'
64

65
// Convert domain names
66
const unicodeDomain = toUnicode('xn--maana-pta.com');  // 'mañana.com'
67
const asciiDomain = toASCII('mañana.com');  // 'xn--maana-pta.com'
68

69
// Convert between strings and code points
70
const codePoints = ucs2decode('abc');  // [0x61, 0x62, 0x63]
71
const string = ucs2encode([0x61, 0x62, 0x63]);  // 'abc'
72
```
73

74
## Capabilities
75

76
### String Encoding and Decoding
77

78
Core Punycode conversion functions for transforming Unicode strings to ASCII-safe representations and vice versa.
79

80
```javascript { .api }
81
/**
82
 * Converts a Punycode string of ASCII-only symbols to a string of Unicode symbols
83
 * @param {string} input - The Punycode string of ASCII-only symbols
84
 * @returns {string} The resulting string of Unicode symbols
85
 * @throws {RangeError} On invalid input or overflow
86
 */
87
function decode(input);
88

89
/**
90
 * Converts a string of Unicode symbols to a Punycode string of ASCII-only symbols
91
 * @param {string} input - The string of Unicode symbols
92
 * @returns {string} The resulting Punycode string of ASCII-only symbols
93
 * @throws {RangeError} On overflow
94
 */
95
function encode(input);
96
```
97

98
**Usage Examples:**
99

100
```javascript
101
// Basic string conversion
102
punycode.encode('mañana');  // 'maana-pta'
103
punycode.decode('maana-pta');  // 'mañana'
104

105
// Unicode characters
106
punycode.encode('☃-⌘');  // '--dqo34k'
107
punycode.decode('--dqo34k');  // '☃-⌘'
108

109
// Complex Unicode strings
110
punycode.encode('他们为什么不说中文');  // 'ihqwcrb4cv8a8dqg056pqjye'
111
punycode.decode('ihqwcrb4cv8a8dqg056pqjye');  // '他们为什么不说中文'
112
```
113

114
### Domain and Email Conversion
115

116
High-level functions for converting complete domain names and email addresses, handling only the parts that need conversion.
117

118
```javascript { .api }
119
/**
120
 * Converts a Punycode string representing a domain name or email address to Unicode
121
 * Only the Punycoded parts of the input will be converted
122
 * @param {string} input - The Punycoded domain name or email address to convert to Unicode
123
 * @returns {string} The Unicode representation of the given Punycode string
124
 */
125
function toUnicode(input);
126

127
/**
128
 * Converts a Unicode string representing a domain name or email address to Punycode
129
 * Only the non-ASCII parts of the domain name will be converted
130
 * @param {string} input - The domain name or email address to convert, as a Unicode string
131
 * @returns {string} The Punycode representation of the given domain name or email address
132
 */
133
function toASCII(input);
134
```
135

136
**Usage Examples:**
137

138
```javascript
139
// Domain name conversion
140
punycode.toASCII('mañana.com');  // 'xn--maana-pta.com'
141
punycode.toUnicode('xn--maana-pta.com');  // 'mañana.com'
142

143
// Email address conversion
144
punycode.toASCII('user@mañana.com');  // 'user@xn--maana-pta.com'
145
punycode.toUnicode('user@xn--maana-pta.com');  // 'user@mañana.com'
146

147
// Multi-part domains
148
punycode.toASCII('☃-⌘.example.com');  // 'xn----dqo34k.example.com'
149
punycode.toUnicode('xn----dqo34k.example.com');  // '☃-⌘.example.com'
150

151
// Safe to call on already converted strings
152
punycode.toASCII('example.com');  // 'example.com' (no change)
153
punycode.toUnicode('example.com');  // 'example.com' (no change)
154
```
155

156
### UCS-2 Utilities
157

158
Low-level utilities for converting between JavaScript's internal character representation (UCS-2) and Unicode code points, with proper handling of surrogate pairs.
159

160
```javascript { .api }
161
/**
162
 * Object containing methods to convert between JavaScript's internal character 
163
 * representation (UCS-2) and Unicode code points
164
 */
165
const ucs2 = {
166
  /**
167
   * Creates an array containing the numeric code points of each Unicode character in the string
168
   * Handles surrogate pairs properly, converting them to single code points (UTF-16 compatible)
169
   * @param {string} string - The Unicode input string (UCS-2)
170
   * @returns {number[]} The new array of numeric code points
171
   */
172
  decode: function(string),
173
  
174
  /**
175
   * Creates a string based on an array of numeric code points
176
   * @param {number[]} codePoints - The array of numeric code points
177
   * @returns {string} The new Unicode string (UCS-2)
178
   */
179
  encode: function(codePoints)
180
};
181
```
182

183
**Usage Examples:**
184

185
```javascript
186
// Convert string to code points
187
punycode.ucs2.decode('abc');  // [0x61, 0x62, 0x63]
188
punycode.ucs2.decode('♥');  // [0x2665]
189

190
// Handle surrogate pairs properly
191
punycode.ucs2.decode('\uD834\uDF06');  // [0x1D306] (single code point)
192

193
// Convert code points back to string
194
punycode.ucs2.encode([0x61, 0x62, 0x63]);  // 'abc'
195
punycode.ucs2.encode([0x1D306]);  // '\uD834\uDF06'
196

197
// Work with mixed content
198
const input = 'Hello ♥ World';
199
const codePoints = punycode.ucs2.decode(input);
200
const restored = punycode.ucs2.encode(codePoints);
201
console.log(restored === input);  // true
202
```
203

204
### Version Information
205

206
Access to the current library version.
207

208
```javascript { .api }
209
/**
210
 * A string representing the current Punycode.js version number
211
 * @type {string}
212
 */
213
const version;
214
```
215

216
**Usage Example:**
217

218
```javascript
219
console.log(punycode.version);  // '2.3.1'
220
```
221

222
## Error Handling
223

224
All punycode functions may throw `RangeError` exceptions in the following cases:
225

226
- **Overflow**: Input needs wider integers to process
227
- **Invalid input**: Input contains invalid characters or sequences
228
- **Not basic**: Input contains illegal characters (>= 0x80) in contexts requiring basic code points
229

230
```javascript
231
try {
232
  const result = punycode.decode('invalid-input');
233
} catch (error) {
234
  if (error instanceof RangeError) {
235
    console.error('Punycode error:', error.message);
236
    // Handle specific error cases
237
  }
238
}
239
```
240

241
## Types
242

243
```javascript { .api }
244
// All functions are available on the main punycode object
245
interface Punycode {
246
  decode(input: string): string;
247
  encode(input: string): string;
248
  toUnicode(input: string): string;
249
  toASCII(input: string): string;
250
  ucs2: {
251
    decode(string: string): number[];
252
    encode(codePoints: number[]): string;
253
  };
254
  version: string;
255
}
256
```