0
# ZIP Generation
1

2
Generate ZIP files in various output formats with compression options, progress tracking, and platform-specific optimizations. Supports asynchronous generation, streaming output, and customizable compression settings.
3

4
## Capabilities
5

6
### Asynchronous Generation
7

8
Generate complete ZIP files asynchronously in various output formats.
9

10
```javascript { .api }
11
/**
12
 * Generate ZIP file asynchronously
13
 * @param options - Generation options including output type and compression
14
 * @param onUpdate - Optional progress callback function
15
 * @returns Promise resolving to the generated ZIP in the specified format
16
 */
17
generateAsync<T extends OutputType>(
18
  options?: JSZipGeneratorOptions<T>, 
19
  onUpdate?: OnUpdateCallback
20
): Promise<OutputByType[T]>;
21
```
22

23
**Usage Examples:**
24

25
```javascript
26
import JSZip from "jszip";
27

28
const zip = new JSZip();
29
zip.file("hello.txt", "Hello World");
30
zip.file("data.json", JSON.stringify({foo: "bar"}));
31

32
// Generate as Blob (for browsers)
33
const blob = await zip.generateAsync({type: "blob"});
34

35
// Generate as ArrayBuffer
36
const arrayBuffer = await zip.generateAsync({type: "arraybuffer"});
37

38
// Generate as Base64 string
39
const base64 = await zip.generateAsync({type: "base64"});
40

41
// Generate as Node.js Buffer
42
const buffer = await zip.generateAsync({type: "nodebuffer"});
43

44
// Generate with compression options
45
const compressedBlob = await zip.generateAsync({
46
  type: "blob",
47
  compression: "DEFLATE",
48
  compressionOptions: { level: 9 }
49
});
50

51
// Generate with progress tracking
52
const zipWithProgress = await zip.generateAsync(
53
  { type: "blob" },
54
  (metadata) => {
55
    console.log(`Progress: ${metadata.percent}%`);
56
    console.log(`Current file: ${metadata.currentFile}`);
57
  }
58
);
59
```
60

61
### Node.js Stream Generation
62

63
Generate ZIP files as Node.js ReadableStream for efficient handling of large archives.
64

65
```javascript { .api }
66
/**
67
 * Generate ZIP as Node.js ReadableStream
68
 * @param options - Generation options (type is always 'nodebuffer')
69
 * @param onUpdate - Optional progress callback function
70
 * @returns Node.js ReadableStream containing the ZIP data
71
 */
72
generateNodeStream(
73
  options?: JSZipGeneratorOptions<'nodebuffer'>, 
74
  onUpdate?: OnUpdateCallback
75
): NodeJS.ReadableStream;
76
```
77

78
**Usage Examples:**
79

80
```javascript
81
import JSZip from "jszip";
82
import fs from "fs";
83

84
const zip = new JSZip();
85
zip.file("large-file.txt", largeTextContent);
86

87
// Generate as stream and pipe to file
88
const stream = zip.generateNodeStream({
89
  compression: "DEFLATE",
90
  streamFiles: true
91
});
92

93
stream.pipe(fs.createWriteStream("output.zip"));
94

95
// Handle stream events
96
stream.on('data', (chunk) => {
97
  console.log(`Received ${chunk.length} bytes`);
98
});
99

100
stream.on('end', () => {
101
  console.log('ZIP generation complete');
102
});
103

104
// Generate with progress tracking
105
const progressStream = zip.generateNodeStream(
106
  { compression: "DEFLATE" },
107
  (metadata) => {
108
    console.log(`Progress: ${metadata.percent}%`);
109
  }
110
);
111
```
112

113
### Internal Stream Generation
114

115
Generate ZIP using the internal StreamHelper for advanced streaming scenarios.
116

117
```javascript { .api }
118
/**
119
 * Generate ZIP using internal streaming implementation
120
 * @param options - Generation options
121
 * @returns JSZipStreamHelper for advanced stream handling
122
 */
123
generateInternalStream<T extends OutputType>(
124
  options?: JSZipGeneratorOptions<T>
125
): JSZipStreamHelper<OutputByType[T]>;
126
```
127

128
**Usage Examples:**
129

130
```javascript
131
import JSZip from "jszip";
132

133
const zip = new JSZip();
134
zip.file("stream-test.txt", "Streaming content");
135

136
// Generate internal stream
137
const streamHelper = zip.generateInternalStream({
138
  type: "uint8array",
139
  compression: "DEFLATE"
140
});
141

142
// Use stream helper methods
143
streamHelper
144
  .on('data', (chunk, metadata) => {
145
    console.log(`Chunk size: ${chunk.length}`);
146
    console.log(`Progress: ${metadata.percent}%`);
147
  })
148
  .on('end', () => {
149
    console.log('Stream finished');
150
  })
151
  .on('error', (error) => {
152
    console.error('Stream error:', error);
153
  })
154
  .resume(); // Start the stream
155

156
// Accumulate entire result
157
const fullResult = await streamHelper.accumulate((metadata) => {
158
  console.log(`Progress: ${metadata.percent}%`);
159
});
160
```
161

162
## Generation Options
163

164
Configure ZIP generation behavior, compression, and output format.
165

166
```javascript { .api }
167
interface JSZipGeneratorOptions<T extends OutputType = OutputType> {
168
  /** Output format type */
169
  type?: T;
170
  /** Compression method for all files */
171
  compression?: Compression;
172
  /** Compression options for DEFLATE */
173
  compressionOptions?: CompressionOptions | null;
174
  /** Global comment for the ZIP file */
175
  comment?: string;
176
  /** MIME type for the generated file */
177
  mimeType?: string;
178
  /** Custom filename encoding function */
179
  encodeFileName?(filename: string): string;
180
  /** Enable streaming for individual files */
181
  streamFiles?: boolean;
182
  /** Platform type for file attributes */
183
  platform?: 'DOS' | 'UNIX';
184
}
185

186
interface CompressionOptions {
187
  /** Compression level (1-9) for DEFLATE */
188
  level: number;
189
}
190
```
191

192
**Usage Examples:**
193

194
```javascript
195
const zip = new JSZip();
196
zip.file("document.txt", documentContent);
197

198
// Basic generation with compression
199
const result = await zip.generateAsync({
200
  type: "blob",
201
  compression: "DEFLATE",
202
  compressionOptions: { level: 6 }
203
});
204

205
// Generate with metadata
206
const zipWithMetadata = await zip.generateAsync({
207
  type: "arraybuffer",
208
  comment: "Generated with JSZip v3.10.1",
209
  mimeType: "application/zip",
210
  platform: "UNIX"
211
});
212

213
// Generate with custom filename encoding
214
const customEncoded = await zip.generateAsync({
215
  type: "base64",
216
  encodeFileName: (filename) => {
217
    // Custom encoding for special characters
218
    return filename.replace(/[^\x00-\x7F]/g, "_");
219
  }
220
});
221

222
// Generate with streaming enabled (better for large files)
223
const streamingZip = await zip.generateAsync({
224
  type: "nodebuffer",
225
  streamFiles: true,
226
  compression: "DEFLATE"
227
});
228
```
229

230
## Output Types
231

232
The various output formats supported by ZIP generation.
233

234
```javascript { .api }
235
type OutputType = keyof OutputByType;
236

237
interface OutputByType {
238
  base64: string;
239
  string: string;
240
  text: string;
241
  binarystring: string;
242
  array: number[];
243
  uint8array: Uint8Array;
244
  arraybuffer: ArrayBuffer;
245
  blob: Blob;
246
  nodebuffer: Buffer;
247
}
248
```
249

250
**Usage Examples:**
251

252
```javascript
253
const zip = new JSZip();
254
zip.file("example.txt", "Example content");
255

256
// String outputs
257
const base64String = await zip.generateAsync({type: "base64"});
258
const binaryString = await zip.generateAsync({type: "binarystring"});
259
const textString = await zip.generateAsync({type: "string"});
260

261
// Binary outputs  
262
const uint8Array = await zip.generateAsync({type: "uint8array"});
263
const arrayBuffer = await zip.generateAsync({type: "arraybuffer"});
264
const numberArray = await zip.generateAsync({type: "array"});
265

266
// Platform-specific outputs
267
const blob = await zip.generateAsync({type: "blob"}); // Browser
268
const buffer = await zip.generateAsync({type: "nodebuffer"}); // Node.js
269
```
270

271
## Progress Tracking
272

273
Monitor ZIP generation progress with detailed metadata.
274

275
```javascript { .api }
276
interface JSZipMetadata {
277
  /** Completion percentage (0-100) */
278
  percent: number;
279
  /** Currently processing file path */
280
  currentFile: string | null;
281
}
282

283
type OnUpdateCallback = (metadata: JSZipMetadata) => void;
284
```
285

286
**Usage Examples:**
287

288
```javascript
289
const zip = new JSZip();
290
// Add multiple files...
291

292
// Track progress during generation
293
const result = await zip.generateAsync(
294
  { type: "blob", compression: "DEFLATE" },
295
  (metadata) => {
296
    // Update progress bar
297
    updateProgressBar(metadata.percent);
298
    
299
    // Show current file
300
    if (metadata.currentFile) {
301
      console.log(`Processing: ${metadata.currentFile}`);
302
    }
303
    
304
    // Check if complete
305
    if (metadata.percent === 100) {
306
      console.log("ZIP generation completed!");
307
    }
308
  }
309
);
310

311
// Progress tracking with streaming
312
const stream = zip.generateNodeStream(
313
  { compression: "DEFLATE" },
314
  (metadata) => {
315
    document.getElementById('progress').textContent = 
316
      `${metadata.percent}% - ${metadata.currentFile || 'Finalizing...'}`;
317
  }
318
);
319
```
320

321
## Platform Considerations
322

323
Handle platform-specific differences between browser and Node.js environments.
324

325
**Browser Usage:**
326

327
```javascript
328
// Use Blob for file downloads
329
const blob = await zip.generateAsync({type: "blob"});
330
const url = URL.createObjectURL(blob);
331
const a = document.createElement('a');
332
a.href = url;
333
a.download = 'archive.zip';
334
a.click();
335
URL.revokeObjectURL(url);
336

337
// Use ArrayBuffer for binary processing
338
const arrayBuffer = await zip.generateAsync({type: "arraybuffer"});
339
const view = new Uint8Array(arrayBuffer);
340
```
341

342
**Node.js Usage:**
343

344
```javascript
345
import fs from 'fs';
346

347
// Use Buffer for file system operations
348
const buffer = await zip.generateAsync({type: "nodebuffer"});
349
fs.writeFileSync('output.zip', buffer);
350

351
// Use streams for large files
352
const stream = zip.generateNodeStream({streamFiles: true});
353
stream.pipe(fs.createWriteStream('large-archive.zip'));
354
```