0
# Unzipper
1

2
Unzipper is a cross-platform streaming API for ZIP file extraction and manipulation in Node.js environments. It provides multiple methods for opening ZIP files from various sources including local files, URLs, Amazon S3, and in-memory buffers, with support for streaming individual files without loading entire archives into memory. It also supports Chrome extension (CRX) files.
3

4
## Package Information
5

6
- **Package Name**: unzipper
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install unzipper`
10

11
## Core Imports
12

13
```javascript
14
const { Parse, ParseOne, Extract, Open } = require("unzipper");
15
```
16

17
For ES modules:
18

19
```javascript
20
import { Parse, ParseOne, Extract, Open } from "unzipper";
21
```
22

23
## Basic Usage
24

25
```javascript
26
const unzipper = require("unzipper");
27
const fs = require("fs");
28

29
// Extract entire ZIP archive to directory
30
fs.createReadStream("archive.zip")
31
  .pipe(unzipper.Extract({ path: "output" }));
32

33
// Parse ZIP file and handle each entry
34
fs.createReadStream("archive.zip")
35
  .pipe(unzipper.Parse())
36
  .on("entry", (entry) => {
37
    const fileName = entry.path;
38
    const type = entry.type; // 'Directory' or 'File'
39
    
40
    if (type === "File") {
41
      entry.pipe(fs.createWriteStream(fileName));
42
    } else {
43
      entry.autodrain();
44
    }
45
  });
46

47
// Open ZIP file and access directory structure
48
const directory = await unzipper.Open.file("archive.zip");
49
const file = directory.files.find(f => f.path === "readme.txt");
50
const content = await file.buffer(); // or file.stream()
51
```
52

53
## Architecture
54

55
Unzipper is designed around streaming principles with four core components:
56

57
- **Parse Stream**: Low-level streaming parser that emits events for each ZIP entry
58
- **ParseOne Stream**: Specialized parser for extracting single files from archives
59
- **Extract Stream**: High-level transform stream for complete archive extraction
60
- **Open Interface**: Promise-based API for random access to ZIP contents from multiple sources
61
- **Entry Objects**: Represent individual files/directories with metadata and streaming access
62

63
The library maintains a low memory footprint through stream-based processing, allowing handling of large archives without loading them entirely into memory.
64

65
## Capabilities
66

67
### Stream Parsing
68

69
Low-level streaming ZIP parser that processes archives entry-by-entry, ideal for selective extraction and custom processing workflows.
70

71
```javascript { .api }
72
class Parse extends PullStream {
73
  constructor(options?: ParseOptions);
74
  promise(): Promise<void>;
75
  autodrain(): void;
76
  buffer(): void;
77
}
78

79
interface ParseOptions {
80
  verbose?: boolean;
81
}
82
```
83

84
[Stream Parsing](./parsing.md)
85

86
### Single File Extraction
87

88
Specialized parser for extracting only the first matching file from a ZIP archive, perfect for scenarios where you need specific files without processing the entire archive.
89

90
```javascript { .api }
91
function ParseOne(match?: RegExp): Parse;
92
```
93

94
[Single File Extraction](./parse-one.md)
95

96
### Full Archive Extraction
97

98
Transform stream for extracting entire ZIP archives to the filesystem with configurable concurrency and destination paths.
99

100
```javascript { .api }
101
class Extract extends Transform {
102
  constructor(options: ExtractOptions);
103
}
104

105
interface ExtractOptions {
106
  path: string;
107
  concurrency?: number;
108
}
109
```
110

111
[Full Archive Extraction](./extraction.md)
112

113
### Random Access Interface
114

115
Promise-based API for opening ZIP files from multiple sources (filesystem, URLs, S3, buffers) and accessing their contents with random access patterns.
116

117
```javascript { .api }
118
interface Open {
119
  file(path: string, options?: OpenOptions): Promise<Directory>;
120
  url(requestLibrary: any, url: string, options?: OpenOptions): Promise<Directory>;
121
  s3(awsSdk: any, params: S3Parameters, options?: OpenOptions): Promise<Directory>;
122
  buffer(buffer: Buffer, options?: OpenOptions): Promise<Directory>;
123
  custom(source: any, options?: OpenOptions): Promise<Directory>;
124
}
125

126
interface Directory {
127
  files: File[];
128
  extract(): Promise<void>;
129
}
130

131
interface File {
132
  path: string;
133
  type: string;
134
  stream(): ReadableStream;
135
  buffer(): Promise<Buffer>;
136
}
137
```
138

139
[Random Access Interface](./open.md)
140

141
## Types
142

143
```javascript { .api }
144
interface Entry {
145
  path: string;
146
  type: 'Directory' | 'File';
147
  vars: {
148
    uncompressedSize: number;
149
  };
150
  props: object;
151
  extra: object;
152
  pipe(destination: WritableStream): void;
153
  autodrain(): void;
154
}
155

156
interface OpenOptions {
157
  /** Enable verbose logging during operations */
158
  verbose?: boolean;
159
  /** Custom encoding for text files */
160
  encoding?: string;
161
  /** Additional configuration options */
162
  [key: string]: any;
163
}
164

165
interface S3Parameters {
166
  Bucket: string;
167
  Key: string;
168
  // Additional S3 parameters
169
}
170
```