0
# JSZip
1

2
JSZip is a comprehensive JavaScript library for creating, reading, and editing ZIP archives in both browser and Node.js environments. It provides a simple and intuitive API for ZIP file manipulation, supporting various data formats including strings, arrays, Uint8Arrays, ArrayBuffers, and Blobs. The library features async/sync operations for generating ZIP files, supports compression with DEFLATE algorithm, handles folder structures, and includes comprehensive TypeScript definitions.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
import JSZip from "jszip";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const JSZip = require("jszip");
21
```
22

23
## Basic Usage
24

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

28
// Create a new ZIP file
29
const zip = new JSZip();
30

31
// Add files to the ZIP
32
zip.file("hello.txt", "Hello World\n");
33
zip.file("data.json", JSON.stringify({name: "example", value: 42}));
34

35
// Create a folder and add a file to it
36
const imgFolder = zip.folder("images");
37
imgFolder.file("logo.png", imageData, {base64: true});
38

39
// Generate the ZIP file
40
const content = await zip.generateAsync({type: "blob"});
41

42
// For Node.js, generate as buffer
43
const buffer = await zip.generateAsync({type: "nodebuffer"});
44

45
// Load an existing ZIP file
46
const loadedZip = await JSZip.loadAsync(zipFileData);
47
const fileContent = await loadedZip.file("hello.txt").async("string");
48
```
49

50
## Architecture
51

52
JSZip is built around several key components:
53

54
- **JSZip Constructor**: Main class for creating and manipulating ZIP instances
55
- **File Operations**: Methods for adding, retrieving, and removing files and folders
56
- **Data Format Support**: Handles multiple input/output formats (strings, arrays, buffers, blobs)
57
- **Compression Engine**: DEFLATE and STORE compression algorithms via pako library
58
- **Streaming Interface**: StreamHelper for handling large files and progress tracking
59
- **Platform Compatibility**: Feature detection and polyfills for browser/Node.js differences
60

61
## Capabilities
62

63
### File and Folder Operations
64

65
Core functionality for adding, retrieving, and managing files and folders within ZIP archives. Supports hierarchical folder structures and file metadata.
66

67
```javascript { .api }
68
// Add or retrieve files
69
file(path: string): JSZipObject | null;
70
file(path: RegExp): JSZipObject[];
71
file<T extends InputType>(path: string, data: InputByType[T] | Promise<InputByType[T]>, options?: JSZipFileOptions): JSZip;
72

73
// Create and navigate folders
74
folder(name: string): JSZip | null;
75
folder(name: RegExp): JSZipObject[];
76

77
// Remove files or folders
78
remove(path: string): JSZip;
79

80
// Create a deep copy of the ZIP instance
81
clone(): JSZip;
82
```
83

84
[File and Folder Operations](./file-operations.md)
85

86
### ZIP Generation
87

88
Generate ZIP files in various formats with compression options, progress tracking, and platform-specific optimizations.
89

90
```javascript { .api }
91
// Generate ZIP asynchronously
92
generateAsync<T extends OutputType>(options?: JSZipGeneratorOptions<T>, onUpdate?: OnUpdateCallback): Promise<OutputByType[T]>;
93

94
// Generate as Node.js stream
95
generateNodeStream(options?: JSZipGeneratorOptions<'nodebuffer'>, onUpdate?: OnUpdateCallback): NodeJS.ReadableStream;
96

97
// Generate using internal streaming
98
generateInternalStream<T extends OutputType>(options?: JSZipGeneratorOptions<T>): JSZipStreamHelper<OutputByType[T]>;
99
```
100

101
[ZIP Generation](./generation.md)
102

103
### ZIP Loading
104

105
Load and parse existing ZIP files from various input sources with validation and error handling capabilities.
106

107
```javascript { .api }
108
// Load ZIP data (static method)
109
static loadAsync(content: InputFileFormat, options?: JSZipLoadOptions): Promise<JSZip>;
110

111
// Load ZIP data (instance method) 
112
loadAsync(data: InputFileFormat, options?: JSZipLoadOptions): Promise<JSZip>;
113
```
114

115
[ZIP Loading](./loading.md)
116

117
### File Content Extraction
118

119
Extract file contents from ZIP archives in various formats with support for streaming and progress tracking.
120

121
```javascript { .api }
122
// JSZipObject methods for content extraction
123
async<T extends OutputType>(type: T, onUpdate?: OnUpdateCallback): Promise<OutputByType[T]>;
124
nodeStream(type?: 'nodebuffer', onUpdate?: OnUpdateCallback): NodeJS.ReadableStream;
125
```
126

127
[File Content Extraction](./extraction.md)
128

129
### Utility and Configuration
130

131
Static properties providing feature detection, version information, and configuration options.
132

133
```javascript { .api }
134
// Static properties
135
static version: string;
136
static support: JSZipSupport;
137
static defaults: object;
138
static external: { Promise: PromiseConstructorLike };
139
```
140

141
[Utility and Configuration](./utilities.md)
142

143
## Types
144

145
### Core Types
146

147
```typescript { .api }
148
type Compression = 'STORE' | 'DEFLATE';
149
type InputFileFormat = InputByType[keyof InputByType] | Promise<InputByType[keyof InputByType]>;
150

151
interface JSZipSupport {
152
  arraybuffer: boolean;
153
  uint8array: boolean;
154
  blob: boolean;
155
  nodebuffer: boolean;
156
  nodestream: boolean;
157
}
158
```
159

160
### Input/Output Format Types
161

162
```typescript { .api }
163
interface InputByType {
164
  base64: string;
165
  string: string;
166
  text: string;
167
  binarystring: string;
168
  array: number[];
169
  uint8array: Uint8Array;
170
  arraybuffer: ArrayBuffer;
171
  blob: Blob;
172
  stream: NodeJS.ReadableStream;
173
}
174

175
interface OutputByType {
176
  base64: string;
177
  string: string;
178
  text: string;
179
  binarystring: string;
180
  array: number[];
181
  uint8array: Uint8Array;
182
  arraybuffer: ArrayBuffer;
183
  blob: Blob;
184
  nodebuffer: Buffer;
185
}
186
```
187

188
### Configuration Types
189

190
```typescript { .api }
191
interface JSZipFileOptions {
192
  base64?: boolean;
193
  binary?: boolean;
194
  date?: Date;
195
  compression?: Compression;
196
  compressionOptions?: CompressionOptions | null;
197
  comment?: string;
198
  optimizedBinaryString?: boolean;
199
  createFolders?: boolean;
200
  dir?: boolean;
201
  dosPermissions?: number | null;
202
  unixPermissions?: number | string | null;
203
}
204

205
interface JSZipLoadOptions {
206
  base64?: boolean;
207
  checkCRC32?: boolean;
208
  optimizedBinaryString?: boolean;
209
  createFolders?: boolean;
210
  decodeFileName?: (bytes: string[] | Uint8Array | Buffer) => string;
211
}
212

213
interface JSZipGeneratorOptions<T extends OutputType = OutputType> {
214
  compression?: Compression;
215
  compressionOptions?: CompressionOptions | null;
216
  type?: T;
217
  comment?: string;
218
  mimeType?: string;
219
  encodeFileName?(filename: string): string;
220
  streamFiles?: boolean;
221
  platform?: 'DOS' | 'UNIX';
222
}
223
```
224

225
### Object Types
226

227
```typescript { .api }
228
interface JSZipObject {
229
  name: string;
230
  unsafeOriginalName?: string;
231
  dir: boolean;
232
  date: Date;
233
  comment: string;
234
  unixPermissions: number | string | null;
235
  dosPermissions: number | null;
236
  options: JSZipObjectOptions;
237
}
238

239
interface JSZipMetadata {
240
  percent: number;
241
  currentFile: string | null;
242
}
243

244
type OnUpdateCallback = (metadata: JSZipMetadata) => void;
245
```