0
# iconv-lite
1

2
iconv-lite is a pure JavaScript character encoding conversion library that enables developers to convert text between different character encodings without requiring native code compilation. It offers both synchronous encode/decode APIs and streaming support for handling large data efficiently, supports a comprehensive range of encodings, and is designed for maximum portability and performance across Node.js, browsers, React Native, and sandboxed environments.
3

4
## Package Information
5

6
- **Package Name**: iconv-lite
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install iconv-lite`
10

11
## Core Imports
12

13
```javascript
14
const iconv = require('iconv-lite');
15
```
16

17
For ES modules:
18

19
```javascript
20
import * as iconv from 'iconv-lite';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const iconv = require('iconv-lite');
27

28
// Convert from an encoded buffer to a js string
29
const str = iconv.decode(Buffer.from([0x68, 0x65, 0x6c, 0x6c, 0x6f]), 'win1251');
30

31
// Convert from a js string to an encoded buffer
32
const buf = iconv.encode("Sample input string", 'win1251');
33

34
// Check if encoding is supported
35
const isSupported = iconv.encodingExists("us-ascii");
36
```
37

38
## Architecture
39

40
iconv-lite is built around several key components:
41

42
- **Core API**: Synchronous `encode()` and `decode()` functions for simple conversions
43
- **Streaming API**: Transform streams for handling large data with `encodeStream()` and `decodeStream()`
44
- **Codec System**: Pluggable encoding system with lazy-loaded codecs for different character sets
45
- **BOM Handling**: Automatic Byte Order Mark detection and manipulation for UTF encodings
46
- **Encoding Support**: Comprehensive support for UTF, ISO, Windows, ASCII, and multibyte encodings
47

48
## Capabilities
49

50
### Core Encoding/Decoding
51

52
Synchronous character encoding conversion between strings and buffers. Essential for processing text data in different character encodings.
53

54
```javascript { .api }
55
function encode(content, encoding, options);
56

57
function decode(buffer, encoding, options);
58

59
function encodingExists(encoding);
60
```
61

62
[Core Encoding API](./core-encoding.md)
63

64
### Streaming API
65

66
Transform streams for encoding and decoding large amounts of data efficiently. Perfect for processing files or network streams.
67

68
```javascript { .api }
69
function encodeStream(encoding, options);
70

71
function decodeStream(encoding, options);
72

73
function enableStreamingAPI(streamModule);
74
```
75

76
[Streaming API](./streaming.md)
77

78
### Low-level API
79

80
Direct access to encoder and decoder instances for advanced use cases and custom stream implementations.
81

82
```javascript { .api }
83
function getEncoder(encoding, options);
84

85
function getDecoder(encoding, options);
86

87
function getCodec(encoding);
88
```
89

90
[Low-level API](./low-level.md)
91

92
## Types
93

94
```javascript { .api }
95
/**
96
 * Options interface for encode/decode functions
97
 */
98
const Options = {
99
  /** Strip BOM (Byte Order Mark) from decoded output (default: true for decode) */
100
  stripBOM,
101
  /** Add BOM to encoded output (default: false) */
102
  addBOM,
103
  /** Default encoding fallback */
104
  defaultEncoding
105
};
106

107
/**
108
 * Encoder stream interface
109
 */
110
const EncoderStream = {
111
  write(str),
112
  end()
113
};
114

115
/**
116
 * Decoder stream interface
117
 */
118
const DecoderStream = {
119
  write(buf),
120
  end()
121
};
122
```
123

124
## Properties and Constants
125

126
```javascript { .api }
127
/** Registry of all available encodings and aliases (lazy-loaded, initially null) */
128
const encodings;
129

130
/** Default character for Unicode encoding errors */
131
const defaultCharUnicode; // "�"
132

133
/** Default character for single-byte encoding errors */
134
const defaultCharSingleByte; // "?"
135

136
/** Boolean indicating if streaming API is currently enabled */
137
const supportsStreams;
138

139
/** Flag to suppress deprecation warnings for decode() with strings */
140
const skipDecodeWarning;
141

142
/** Internal cache of loaded codec instances */
143
const _codecDataCache;
144

145
/** BOM (Byte Order Mark) character constant */
146
const BOMChar; // "\uFEFF"
147
```
148

149
## Supported Encodings
150

151
iconv-lite supports a comprehensive range of character encodings:
152

153
- **UTF Encodings**: UTF-8, UTF-16, UTF-16BE, UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7
154
- **ISO Encodings**: ISO-8859 family (1-16)
155
- **Windows Encodings**: Windows-125x family (1250-1258)
156
- **ASCII Encodings**: US-ASCII and variants
157
- **Multibyte Encodings**: CP932, GB2312, GBK, Big5, Shift_JIS, EUC-JP, EUC-KR
158
- **Special Encodings**: CESU-8, UCS-2, Binary, Base64, Hex