0
# Streaming API
1

2
Transform streams for encoding and decoding large amounts of data efficiently. The streaming API is automatically enabled in Node.js environments but can be manually controlled for browser compatibility.
3

4
## Capabilities
5

6
### Encode Stream
7

8
Creates a transform stream that encodes string input to buffer output using the specified character encoding.
9

10
```javascript { .api }
11
/**
12
 * Create encoding transform stream
13
 * @param encoding - Target encoding name
14
 * @param options - Stream and encoding options
15
 * @returns Transform stream that encodes strings to buffers
16
 */
17
function encodeStream(encoding, options);
18
```
19

20
**Usage Examples:**
21

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

26
// File encoding example
27
fs.createReadStream('input.txt', 'utf8')
28
  .pipe(iconv.encodeStream('win1251'))
29
  .pipe(fs.createWriteStream('output-win1251.txt'));
30

31
// HTTP response encoding
32
app.get('/data', (req, res) => {
33
  const encoder = iconv.encodeStream('iso-8859-1');
34
  dataStream.pipe(encoder).pipe(res);
35
});
36

37
// With BOM
38
const encoderWithBOM = iconv.encodeStream('utf16le', { addBOM: true });
39
```
40

41
### Decode Stream
42

43
Creates a transform stream that decodes buffer input to string output using the specified character encoding.
44

45
```javascript { .api }
46
/**
47
 * Create decoding transform stream
48
 * @param encoding - Source encoding name
49
 * @param options - Stream and encoding options
50
 * @returns Transform stream that decodes buffers to strings
51
 */
52
function decodeStream(encoding, options);
53
```
54

55
**Usage Examples:**
56

57
```javascript
58
const iconv = require('iconv-lite');
59
const http = require('http');
60

61
// HTTP request decoding
62
http.createServer((req, res) => {
63
  const decoder = iconv.decodeStream('win1251');
64
  req.pipe(decoder);
65
  
66
  decoder.on('data', (str) => {
67
    console.log(str); // Decoded string chunks
68
  });
69
});
70

71
// File conversion
72
fs.createReadStream('input-gbk.txt')
73
  .pipe(iconv.decodeStream('gbk'))
74
  .pipe(iconv.encodeStream('utf8'))
75
  .pipe(fs.createWriteStream('output-utf8.txt'));
76

77
// With BOM preservation
78
const decoder = iconv.decodeStream('utf16le', { stripBOM: false });
79
```
80

81
### Enable Streaming API
82

83
Manually enables the streaming API with a custom stream module. This is useful in environments where the stream module is not automatically available.
84

85
```javascript { .api }
86
/**
87
 * Enable streaming API with custom stream module
88
 * @param streamModule - Node.js stream module or compatible implementation
89
 */
90
function enableStreamingAPI(streamModule);
91
```
92

93
**Usage Examples:**
94

95
```javascript
96
const iconv = require('iconv-lite');
97
const stream = require('stream');
98

99
// Manual streaming API activation
100
iconv.enableStreamingAPI(stream);
101

102
// In React Native or other environments
103
const stream = require('stream-browserify');
104
iconv.enableStreamingAPI(stream);
105

106
// Check if streaming is available
107
if (iconv.supportsStreams) {
108
  const decoder = iconv.decodeStream('utf8');
109
}
110
```
111

112
## Stream Classes
113

114
When streaming API is enabled, these classes become available:
115

116
### IconvLiteEncoderStream
117

118
Transform stream class for encoding strings to buffers.
119

120
```javascript { .api }
121
/**
122
 * Transform stream for encoding strings to buffers
123
 * @param conv - Encoder instance from getEncoder()
124
 * @param options - Stream options
125
 */
126
class IconvLiteEncoderStream extends Transform {
127
  constructor(conv, options);
128
  
129
  /**
130
   * Collect all encoded output into a single buffer
131
   * @param cb - Callback receiving (error, buffer)
132
   * @returns this for chaining
133
   */
134
  collect(cb);
135
}
136
```
137

138
**Usage Examples:**
139

140
```javascript
141
const iconv = require('iconv-lite');
142

143
// Direct class usage
144
const encoder = iconv.getEncoder('utf16le');
145
const encoderStream = new iconv.IconvLiteEncoderStream(encoder);
146

147
// Collect output
148
encoderStream.collect((err, buffer) => {
149
  if (err) throw err;
150
  console.log('Encoded data:', buffer);
151
});
152

153
encoderStream.write('Hello ');
154
encoderStream.write('World');
155
encoderStream.end();
156
```
157

158
### IconvLiteDecoderStream
159

160
Transform stream class for decoding buffers to strings.
161

162
```javascript { .api }
163
/**
164
 * Transform stream for decoding buffers to strings
165
 * @param conv - Decoder instance from getDecoder()
166
 * @param options - Stream options
167
 */
168
class IconvLiteDecoderStream extends Transform {
169
  constructor(conv, options);
170
  
171
  /**
172
   * Collect all decoded output into a single string
173
   * @param cb - Callback receiving (error, string)
174
   * @returns this for chaining
175
   */
176
  collect(cb);
177
}
178
```
179

180
**Usage Examples:**
181

182
```javascript
183
const iconv = require('iconv-lite');
184

185
// Direct class usage
186
const decoder = iconv.getDecoder('gbk');
187
const decoderStream = new iconv.IconvLiteDecoderStream(decoder);
188

189
// Collect output
190
decoderStream.collect((err, str) => {
191
  if (err) throw err;
192
  console.log('Decoded text:', str);
193
});
194

195
decoderStream.write(buffer1);
196
decoderStream.write(buffer2);
197
decoderStream.end();
198
```
199

200
## Stream Options
201

202
Stream functions accept the same options as their synchronous counterparts, plus standard Node.js stream options:
203

204
```javascript { .api }
205
/**
206
 * Stream options extending basic Options
207
 */
208
const StreamOptions = {
209
  // Basic options
210
  stripBOM,
211
  addBOM,
212
  defaultEncoding,
213
  
214
  // Transform stream options
215
  /** Transform stream object mode */
216
  objectMode,
217
  /** Transform stream high water mark */
218
  highWaterMark,
219
  /** Transform stream decode strings option */
220
  decodeStrings,
221
  /** Transform stream encoding */
222
  encoding
223
};
224
```
225

226
## Browser Compatibility
227

228
The streaming API is disabled by default in browser environments to reduce bundle size (~100KB savings). Enable it manually when needed:
229

230
```javascript
231
// Check if streams are supported
232
if (!iconv.supportsStreams) {
233
  // Streams not available - will throw error if used
234
  console.log('Streaming API not available');
235
}
236

237
// Enable streams in browser (if stream module available)
238
const stream = require('stream-browserify');
239
iconv.enableStreamingAPI(stream);
240
```
241

242
## Error Handling
243

244
Stream errors are handled through the standard Node.js stream error mechanisms:
245

246
```javascript
247
const decoder = iconv.decodeStream('utf8');
248

249
decoder.on('error', (err) => {
250
  console.error('Decoding error:', err.message);
251
});
252

253
// Encoding errors in streams
254
const encoder = iconv.encodeStream('ascii');
255
encoder.on('error', (err) => {
256
  // Handle encoding errors
257
});
258
```
259

260
## Properties
261

262
```javascript { .api }
263
/** Boolean indicating if streaming API is currently enabled */
264
const supportsStreams;
265
```