0
# Low-level API
1

2
Direct access to encoder and decoder instances for advanced use cases, custom stream implementations, and performance-critical applications.
3

4
## Capabilities
5

6
### Get Encoder
7

8
Returns a low-level encoder instance for the specified encoding that can be used to encode data incrementally.
9

10
```javascript { .api }
11
/**
12
 * Get encoder instance for incremental encoding
13
 * @param encoding - Target encoding name
14
 * @param options - Encoding options
15
 * @returns Encoder instance with write() and end() methods
16
 */
17
function getEncoder(encoding, options);
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
const iconv = require('iconv-lite');
24

25
// Basic encoder usage
26
const encoder = iconv.getEncoder('utf16le');
27
const chunk1 = encoder.write('Hello ');
28
const chunk2 = encoder.write('World');
29
const finalChunk = encoder.end();
30

31
const result = Buffer.concat([chunk1, chunk2, finalChunk || Buffer.alloc(0)]);
32

33
// Encoder with BOM
34
const encoderWithBOM = iconv.getEncoder('utf16le', { addBOM: true });
35
const encoded = encoderWithBOM.write('Text with BOM');
36
const final = encoderWithBOM.end();
37
```
38

39
### Get Decoder
40

41
Returns a low-level decoder instance for the specified encoding that can be used to decode data incrementally.
42

43
```javascript { .api }
44
/**
45
 * Get decoder instance for incremental decoding
46
 * @param encoding - Source encoding name
47
 * @param options - Decoding options
48
 * @returns Decoder instance with write() and end() methods
49
 */
50
function getDecoder(encoding, options);
51
```
52

53
**Usage Examples:**
54

55
```javascript
56
const iconv = require('iconv-lite');
57

58
// Basic decoder usage
59
const decoder = iconv.getDecoder('gbk');
60
const str1 = decoder.write(buffer1);
61
const str2 = decoder.write(buffer2);
62
const finalStr = decoder.end();
63

64
const result = str1 + str2 + (finalStr || '');
65

66
// Decoder with BOM preservation
67
const decoder = iconv.getDecoder('utf16le', { stripBOM: false });
68
const decoded = decoder.write(bufferWithBOM);
69
```
70

71
### Get Codec
72

73
Returns the internal codec object for the specified encoding, providing access to the underlying encoder and decoder constructors.
74

75
```javascript { .api }
76
/**
77
 * Get internal codec for encoding
78
 * @param encoding - Encoding name
79
 * @returns Codec object with encoder and decoder constructors
80
 */
81
function getCodec(encoding);
82
```
83

84
**Usage Examples:**
85

86
```javascript
87
const iconv = require('iconv-lite');
88

89
// Get codec information
90
const codec = iconv.getCodec('utf8');
91
console.log(codec.encodingName); // Canonical encoding name
92
console.log(codec.bomAware);     // Boolean indicating BOM support
93

94
// Create encoder/decoder instances directly
95
const encoder = new codec.encoder({}, codec);
96
const decoder = new codec.decoder({}, codec);
97

98
// Check codec properties
99
if (codec.bomAware) {
100
  console.log('This encoding supports BOM handling');
101
}
102
```
103

104
## Low-level Interfaces
105

106
### Encoder Interface
107

108
Low-level encoder instances returned by `getEncoder()`:
109

110
```javascript { .api }
111
/**
112
 * Encoder stream interface
113
 */
114
const EncoderStream = {
115
  /**
116
   * Encode a string chunk
117
   * @param str - String to encode
118
   * @returns Encoded buffer chunk
119
   */
120
  write(str),
121
  
122
  /**
123
   * Finalize encoding and get any remaining bytes
124
   * @returns Final buffer chunk or undefined
125
   */
126
  end()
127
};
128
```
129

130
### Decoder Interface
131

132
Low-level decoder instances returned by `getDecoder()`:
133

134
```javascript { .api }
135
/**
136
 * Decoder stream interface
137
 */
138
const DecoderStream = {
139
  /**
140
   * Decode a buffer chunk
141
   * @param buf - Buffer to decode
142
   * @returns Decoded string chunk
143
   */
144
  write(buf),
145
  
146
  /**
147
   * Finalize decoding and get any remaining characters
148
   * @returns Final string chunk or undefined
149
   */
150
  end()
151
};
152
```
153

154
### Codec Interface
155

156
Internal codec objects returned by `getCodec()`:
157

158
```javascript { .api }
159
/**
160
 * Codec interface
161
 */
162
const Codec = {
163
  /** Canonical encoding name */
164
  encodingName,
165
  /** Whether this encoding supports BOM handling */
166
  bomAware,
167
  /** Encoder constructor */
168
  encoder,
169
  /** Decoder constructor */
170
  decoder
171
};
172
```
173

174
## Internal Properties
175

176
These internal properties are exposed for advanced use cases but should be used with caution:
177

178
### Codec Data Cache
179

180
```javascript { .api }
181
/**
182
 * Internal cache of loaded codec instances
183
 * Object with null prototype containing codec instances keyed by encoding name
184
 */
185
const _codecDataCache;
186
```
187

188
### Encoding Canonicalization
189

190
```javascript { .api }
191
/**
192
 * Normalize encoding name to canonical form
193
 * @param encoding - Raw encoding name
194
 * @returns Canonicalized encoding name (lowercase, alphanumeric only)
195
 */
196
function _canonicalizeEncoding(encoding);
197
```
198

199
**Usage Examples:**
200

201
```javascript
202
const iconv = require('iconv-lite');
203

204
// Encoding name normalization
205
console.log(iconv._canonicalizeEncoding('UTF-8'));      // 'utf8'
206
console.log(iconv._canonicalizeEncoding('iso-8859-1')); // 'iso88591'
207
console.log(iconv._canonicalizeEncoding('Windows-1252:2000')); // 'windows1252'
208
```
209

210
### Encodings Registry
211

212
```javascript { .api }
213
/**
214
 * Registry of all available encodings and aliases
215
 * Lazy-loaded on first access, initially null
216
 */
217
const encodings;
218
```
219

220
## BOM Handling Classes
221

222
Internal classes used for Byte Order Mark handling:
223

224
### BOM Character Constant
225

226
```javascript { .api }
227
/** BOM (Byte Order Mark) character constant */
228
const BOMChar; // "\uFEFF"
229
```
230

231
### PrependBOM Wrapper
232

233
```javascript { .api }
234
/**
235
 * Encoder wrapper that prepends BOM to output
236
 * @param encoder - Base encoder instance
237
 * @param options - Options (unused)
238
 */
239
class PrependBOMWrapper {
240
  constructor(encoder, options);
241
  write(str);
242
  end();
243
}
244
```
245

246
### StripBOM Wrapper
247

248
```javascript { .api }
249
/**
250
 * Decoder wrapper that strips BOM from output
251
 * @param decoder - Base decoder instance
252
 * @param options - Options with optional stripBOM callback
253
 */
254
class StripBOMWrapper {
255
  constructor(decoder, options);
256
  write(buf);
257
  end();
258
}
259
```
260

261
## Performance Considerations
262

263
- **Incremental Processing**: Use low-level API for processing data in chunks to reduce memory usage
264
- **Codec Caching**: Codecs are cached after first use; repeated calls to `getCodec()` are fast
265
- **BOM Handling**: BOM wrappers add minimal overhead and are applied automatically when needed
266
- **Encoding Validation**: `encodingExists()` is faster than try/catch around `getCodec()`
267

268
## Advanced Usage Patterns
269

270
```javascript
271
const iconv = require('iconv-lite');
272

273
// Custom stream implementation
274
class CustomEncodingStream extends Transform {
275
  constructor(encoding, options) {
276
    super(options);
277
    this.encoder = iconv.getEncoder(encoding, options);
278
  }
279
  
280
  _transform(chunk, encoding, callback) {
281
    try {
282
      const result = this.encoder.write(chunk.toString());
283
      callback(null, result);
284
    } catch (err) {
285
      callback(err);
286
    }
287
  }
288
  
289
  _flush(callback) {
290
    try {
291
      const final = this.encoder.end();
292
      callback(null, final);
293
    } catch (err) {
294
      callback(err);
295
    }
296
  }
297
}
298
```