0
# Stream Parsing
1

2
Stream-based ZIP file parser that processes archives entry-by-entry through event emission. This low-level interface provides maximum flexibility for custom processing workflows and selective extraction patterns.
3

4
## Capabilities
5

6
### Parse Stream Constructor
7

8
Creates a parsing stream that processes ZIP file entries and emits events for each file or directory encountered.
9

10
```javascript { .api }
11
/**
12
 * Creates a streaming ZIP parser that emits entry events
13
 * @param options - Optional configuration object
14
 * @returns Parse stream instance
15
 */
16
class Parse extends PullStream {
17
  constructor(options?: ParseOptions);
18
}
19

20
interface ParseOptions {
21
  /** Enable verbose logging during parsing */
22
  verbose?: boolean;
23
}
24
```
25

26
**Usage Examples:**
27

28
```javascript
29
const unzipper = require("unzipper");
30
const fs = require("fs");
31

32
// Basic parsing with entry handling
33
fs.createReadStream("archive.zip")
34
  .pipe(new unzipper.Parse())
35
  .on("entry", (entry) => {
36
    console.log(`Found: ${entry.path} (${entry.type})`);
37
    
38
    if (entry.type === "File") {
39
      // Process file entry
40
      entry.pipe(fs.createWriteStream(`extracted/${entry.path}`));
41
    } else {
42
      // Skip directory entries
43
      entry.autodrain();
44
    }
45
  })
46
  .on("finish", () => {
47
    console.log("Parsing completed");
48
  });
49

50
// Verbose parsing
51
const parser = new unzipper.Parse({ verbose: true });
52
fs.createReadStream("archive.zip").pipe(parser);
53
```
54

55
### Promise Interface
56

57
Converts the streaming operation to a Promise for async/await compatibility.
58

59
```javascript { .api }
60
/**
61
 * Returns a Promise that resolves when parsing completes
62
 * @returns Promise resolving when stream finishes
63
 */
64
promise(): Promise<void>;
65
```
66

67
**Usage Examples:**
68

69
```javascript
70
const parser = fs.createReadStream("archive.zip")
71
  .pipe(new unzipper.Parse())
72
  .on("entry", (entry) => {
73
    // Handle entries
74
    entry.autodrain();
75
  });
76

77
// Wait for completion
78
await parser.promise();
79
console.log("All entries processed");
80
```
81

82
### Stream Management
83

84
Methods for controlling stream flow and preventing backpressure issues.
85

86
```javascript { .api }
87
/**
88
 * Drains the stream to prevent blocking
89
 */
90
autodrain(): void;
91

92
/**
93
 * Buffers the entire stream contents in memory
94
 */
95
buffer(): void;
96
```
97

98
## Events
99

100
### Entry Event
101

102
Emitted for each file or directory found in the ZIP archive.
103

104
```javascript { .api }
105
/**
106
 * Emitted for each entry (file/directory) in the ZIP archive
107
 * @param entry - Entry object representing the file or directory
108
 */
109
parser.on('entry', (entry: Entry) => {
110
  // Handle entry
111
});
112

113
interface Entry {
114
  /** Path of the file/directory within the archive */
115
  path: string;
116
  /** Type of entry: 'File' or 'Directory' */
117
  type: 'File' | 'Directory';
118
  /** Metadata about the entry */
119
  vars: {
120
    uncompressedSize: number;
121
  };
122
  /** Additional ZIP properties */
123
  props: object;
124
  /** Extra field data */
125
  extra: object;
126
  
127
  /** Pipe entry content to a writable stream */
128
  pipe(destination: WritableStream): WritableStream;
129
  /** Skip this entry and continue parsing */
130
  autodrain(): void;
131
}
132
```
133

134
### Stream Events
135

136
Standard Node.js stream events for monitoring parsing progress.
137

138
```javascript { .api }
139
// Parsing completed successfully
140
parser.on('finish', () => {
141
  console.log('Parsing finished');
142
});
143

144
// End of stream reached
145
parser.on('end', () => {
146
  console.log('Stream ended');
147
});
148

149
// Stream closed
150
parser.on('close', () => {
151
  console.log('Stream closed');
152
});
153

154
// Error occurred during parsing
155
parser.on('error', (error: Error) => {
156
  console.error('Parsing error:', error);
157
});
158

159
// Chrome extension header detected (CRX files)
160
parser.on('crx-header', () => {
161
  console.log('Chrome extension file detected');
162
});
163
```
164

165
## Advanced Usage
166

167
### Selective Extraction
168

169
```javascript
170
const path = require("path");
171
const unzipper = require("unzipper");
172

173
fs.createReadStream("archive.zip")
174
  .pipe(new unzipper.Parse())
175
  .on("entry", (entry) => {
176
    const fileName = entry.path;
177
    const type = entry.type;
178
    
179
    // Only extract .txt files
180
    if (type === "File" && fileName.endsWith(".txt")) {
181
      entry.pipe(fs.createWriteStream(path.basename(fileName)));
182
    } else {
183
      entry.autodrain();
184
    }
185
  });
186
```
187

188
### Entry Filtering and Processing
189

190
```javascript
191
const processedFiles = [];
192

193
fs.createReadStream("archive.zip")
194
  .pipe(new unzipper.Parse())
195
  .on("entry", (entry) => {
196
    if (entry.type === "File" && entry.vars.uncompressedSize > 0) {
197
      // Collect file information
198
      processedFiles.push({
199
        path: entry.path,
200
        size: entry.vars.uncompressedSize
201
      });
202
      
203
      // Process file content
204
      let content = '';
205
      entry.on('data', (chunk) => {
206
        content += chunk.toString();
207
      });
208
      
209
      entry.on('end', () => {
210
        console.log(`Processed ${entry.path}: ${content.length} chars`);
211
      });
212
    } else {
213
      entry.autodrain();
214
    }
215
  })
216
  .on("finish", () => {
217
    console.log(`Processed ${processedFiles.length} files`);
218
  });
219
```