@rahul_dadhich15/archive-kit 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +48 -0
- package/LICENSE +21 -0
- package/README.md +385 -2
- package/dist/gzip/index.cjs +439 -0
- package/dist/gzip/index.cjs.map +1 -0
- package/dist/gzip/index.d.cts +174 -0
- package/dist/gzip/index.d.ts +174 -0
- package/dist/gzip/index.js +424 -0
- package/dist/gzip/index.js.map +1 -0
- package/dist/index.cjs +1320 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +120 -0
- package/dist/index.d.ts +120 -0
- package/dist/index.js +1260 -0
- package/dist/index.js.map +1 -0
- package/dist/types-CY4dTVyZ.d.cts +34 -0
- package/dist/types-CY4dTVyZ.d.ts +34 -0
- package/dist/zip-create/index.cjs +357 -0
- package/dist/zip-create/index.cjs.map +1 -0
- package/dist/zip-create/index.d.cts +120 -0
- package/dist/zip-create/index.d.ts +120 -0
- package/dist/zip-create/index.js +350 -0
- package/dist/zip-create/index.js.map +1 -0
- package/dist/zip-extract/index.cjs +701 -0
- package/dist/zip-extract/index.cjs.map +1 -0
- package/dist/zip-extract/index.d.cts +298 -0
- package/dist/zip-extract/index.d.ts +298 -0
- package/dist/zip-extract/index.js +685 -0
- package/dist/zip-extract/index.js.map +1 -0
- package/package.json +91 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [0.1.0] - 2026-11-21
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
- **GZIP Compression & Decompression**:
|
|
12
|
+
- `gzipCompress` and `gzipDecompress` supporting `Uint8Array`, `ArrayBuffer`, `Blob`, and `File`.
|
|
13
|
+
- `gzipCompressText` and `gzipDecompressText` with strict UTF-8 validation.
|
|
14
|
+
- `gzipCompressBlob` and `gzipDecompressBlob` for browser-native Blob workflows.
|
|
15
|
+
- Synchronous variants: `gzipCompressSync`, `gzipDecompressSync`, `gzipCompressTextSync`, and `gzipDecompressTextSync`.
|
|
16
|
+
- Signature detection: `isGzipData` and `isGzipDataSync`.
|
|
17
|
+
- Comprehensive metadata parsing: `getGzipMetadata` and `getGzipMetadataSync` extracting original uncompressed size (ISIZE), compressed size, ratios, filename, comment, and timestamp.
|
|
18
|
+
- Full trailer CRC-32 and ISIZE integrity verification to prevent corrupted decompression.
|
|
19
|
+
|
|
20
|
+
- **ZIP Archive Creation**:
|
|
21
|
+
- `createZip` and `createZipBlob` supporting files, directories, text, Uint8Array, ArrayBuffer, and Blobs.
|
|
22
|
+
- `createZipFromFiles` with automatic `webkitRelativePath` support for browser folder uploads.
|
|
23
|
+
- STORE (uncompressed) and DEFLATE (configurable levels 0-9) compression modes.
|
|
24
|
+
- Directory structure preservation and empty directory support.
|
|
25
|
+
- Synchronous variant: `createZipSync`.
|
|
26
|
+
- Entry validation: `validateZipEntries` and `getZipCreateOptions`.
|
|
27
|
+
- Global archive comment embedding into End of Central Directory (EOCD).
|
|
28
|
+
|
|
29
|
+
- **ZIP Archive Extraction & Inspection**:
|
|
30
|
+
- `listZipEntries`: Non-decompressing central directory inspection for instant file listings.
|
|
31
|
+
- `extractZip`: Full archive extraction returning structured `ExtractedZipEntry` instances with `.text()` and `.blob()` helpers.
|
|
32
|
+
- `extractZipEntry`: Selective single-entry decompression skipping unrelated archive entries.
|
|
33
|
+
- `isZipArchive` and `isZipArchiveSync` signature detection.
|
|
34
|
+
- `validateZipArchive` providing detailed structural, method, and security audits.
|
|
35
|
+
- `getZipMetadata` summarizing archive stats, counts, and security indicators.
|
|
36
|
+
|
|
37
|
+
- **Security & Threat Mitigations**:
|
|
38
|
+
- Zip Slip / path traversal rejection (detects and blocks `..`, absolute paths, Windows drive letters `C:`, UNC `//`, and NUL bytes).
|
|
39
|
+
- Decompression bomb defenses (configurable compression ratio limits and decompressed byte tracking).
|
|
40
|
+
- Configurable resource limits: `maxEntries`, `maxEntrySize`, `maxTotalSize`, and `maxInputSize`.
|
|
41
|
+
- Verification of CRC-32 checksums on extraction.
|
|
42
|
+
- Explicit rejection of unsupported encryption (passwords/AES) and unsupported compression algorithms.
|
|
43
|
+
|
|
44
|
+
- **Tooling & Architecture**:
|
|
45
|
+
- Dual ESM and CommonJS exports with full TypeScript declaration maps (`.d.ts`, `.d.cts`).
|
|
46
|
+
- Modular subpaths: `@rahul_dadhich15/archive-kit/gzip`, `@rahul_dadhich15/archive-kit/zip-create`, `@rahul_dadhich15/archive-kit/zip-extract`.
|
|
47
|
+
- Single runtime dependency: `fflate`.
|
|
48
|
+
- 100+ automated unit, integration, security, and Playwright real-browser tests.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Rahul Dadhich
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,386 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @rahul_dadhich15/archive-kit
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://github.com/rahuldadhich1517-sys/archive-kit/actions/workflows/ci.yml)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
5
|
+
[](https://www.typescriptlang.org/)
|
|
6
|
+
|
|
7
|
+
Production-ready, browser-first archive and compression toolkit containing three standalone file utilities: **GZIP compression/decompression**, **ZIP archive creation**, and **ZIP archive extraction & inspection**.
|
|
8
|
+
|
|
9
|
+
Engineered specifically for local in-browser file processing (e.g. React, Vite, Next.js, standard web applications) and Node.js environments. All compression, decompression, and inspection happen **locally on the client** without backends, external APIs, telemetry, or remote services.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Features
|
|
14
|
+
|
|
15
|
+
- 🔒 **100% Client-Side Local Processing**: Zero network requests, zero remote processing, zero server dependency.
|
|
16
|
+
- ⚡ **Single Lightweight Runtime Dependency**: Powered exclusively by [`fflate`](https://github.com/101arrowz/fflate) for blazing-fast DEFLATE execution.
|
|
17
|
+
- 📦 **Modular & Tree-Shakeable**: Import only what you need from the root or dedicated subpaths (`/gzip`, `/zip-create`, `/zip-extract`).
|
|
18
|
+
- 🛡️ **Hardened Security**:
|
|
19
|
+
- Full Zip Slip / path traversal protection (`..`, absolute paths, Windows drive letters `C:`, UNC `//`, NUL bytes).
|
|
20
|
+
- Decompression bomb defenses (compression ratio checks and live extracted byte accounting).
|
|
21
|
+
- Configurable resource limits (`maxEntries`, `maxEntrySize`, `maxTotalSize`, `maxCompressionRatio`).
|
|
22
|
+
- Strict CRC-32 and ISIZE integrity verification.
|
|
23
|
+
- 🌐 **Browser-Native**: Native support for `File`, `Blob`, `ArrayBuffer`, and `Uint8Array`.
|
|
24
|
+
- 📁 **Folder Structure Preservation**: Automatic relative path resolution for folder uploads (`webkitRelativePath`).
|
|
25
|
+
- 🔎 **Instant Non-Extracting Inspection**: Inspect archive file lists and metadata directly from the Central Directory without decompressing payload bytes.
|
|
26
|
+
- 🎯 **Selective Extraction**: Extract individual files on-demand without decompressing the rest of the archive.
|
|
27
|
+
- 📘 **TypeScript-First**: Strict TypeScript declarations and JSDoc documentation for all public APIs.
|
|
28
|
+
- 🔄 **Dual ESM & CommonJS**: Full support for standard ESM (`import`) and CommonJS (`require`).
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## Installation
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
npm install @rahul_dadhich15/archive-kit
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Or with yarn / pnpm / bun:
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
yarn add @rahul_dadhich15/archive-kit
|
|
42
|
+
pnpm add @rahul_dadhich15/archive-kit
|
|
43
|
+
bun add @rahul_dadhich15/archive-kit
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## Import Options
|
|
49
|
+
|
|
50
|
+
You can import utilities from the primary root package:
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
import {
|
|
54
|
+
gzipCompress,
|
|
55
|
+
gzipDecompress,
|
|
56
|
+
createZip,
|
|
57
|
+
createZipFromFiles,
|
|
58
|
+
listZipEntries,
|
|
59
|
+
extractZip,
|
|
60
|
+
extractZipEntry
|
|
61
|
+
} from '@rahul_dadhich15/archive-kit';
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Or import from standalone subpaths for optimal bundle tree-shaking:
|
|
65
|
+
|
|
66
|
+
```ts
|
|
67
|
+
// GZIP only
|
|
68
|
+
import { gzipCompressText, gzipDecompressText } from '@rahul_dadhich15/archive-kit/gzip';
|
|
69
|
+
|
|
70
|
+
// ZIP Creation only
|
|
71
|
+
import { createZip, createZipBlob } from '@rahul_dadhich15/archive-kit/zip-create';
|
|
72
|
+
|
|
73
|
+
// ZIP Extraction only
|
|
74
|
+
import { listZipEntries, extractZip } from '@rahul_dadhich15/archive-kit/zip-extract';
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Usage Guide
|
|
80
|
+
|
|
81
|
+
### 1. GZIP Utility (`/gzip`)
|
|
82
|
+
|
|
83
|
+
Compress and decompress data locally using standard RFC 1952 GZIP format.
|
|
84
|
+
|
|
85
|
+
#### Text Compression & Decompression
|
|
86
|
+
|
|
87
|
+
```ts
|
|
88
|
+
import { gzipCompressText, gzipDecompressText } from '@rahul_dadhich15/archive-kit/gzip';
|
|
89
|
+
|
|
90
|
+
const originalText = 'Hello, local browser compression!';
|
|
91
|
+
|
|
92
|
+
// Compress string to Uint8Array
|
|
93
|
+
const compressed = await gzipCompressText(originalText, { level: 6 });
|
|
94
|
+
|
|
95
|
+
// Decompress Uint8Array directly back to string
|
|
96
|
+
const recovered = await gzipDecompressText(compressed);
|
|
97
|
+
console.log(recovered); // "Hello, local browser compression!"
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
#### Binary Data Compression
|
|
101
|
+
|
|
102
|
+
```ts
|
|
103
|
+
import { gzipCompress, gzipDecompress } from '@rahul_dadhich15/archive-kit/gzip';
|
|
104
|
+
|
|
105
|
+
const rawBytes = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
|
|
106
|
+
|
|
107
|
+
// Accepts Uint8Array, ArrayBuffer, Blob, or File
|
|
108
|
+
const compressed = await gzipCompress(rawBytes, {
|
|
109
|
+
level: 9, // 0 = STORE (no compression), 9 = Maximum
|
|
110
|
+
filename: 'data.bin',
|
|
111
|
+
mtime: new Date()
|
|
112
|
+
});
|
|
113
|
+
|
|
114
|
+
const decompressed = await gzipDecompress(compressed);
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
#### Browser Blob Compression & Download Preparation
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
import { gzipCompressBlob, gzipDecompressBlob } from '@rahul_dadhich15/archive-kit/gzip';
|
|
121
|
+
|
|
122
|
+
const fileInput = document.querySelector('input[type="file"]').files[0];
|
|
123
|
+
|
|
124
|
+
// Compresses to a browser-ready Blob with MIME type "application/gzip"
|
|
125
|
+
const compressedBlob = await gzipCompressBlob(fileInput);
|
|
126
|
+
|
|
127
|
+
// Create download link in browser UI
|
|
128
|
+
const downloadUrl = URL.createObjectURL(compressedBlob);
|
|
129
|
+
const link = document.createElement('a');
|
|
130
|
+
link.href = downloadUrl;
|
|
131
|
+
link.download = `${fileInput.name}.gz`;
|
|
132
|
+
link.click();
|
|
133
|
+
URL.revokeObjectURL(downloadUrl);
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
#### GZIP Metadata & Verification
|
|
137
|
+
|
|
138
|
+
```ts
|
|
139
|
+
import { isGzipData, getGzipMetadata } from '@rahul_dadhich15/archive-kit/gzip';
|
|
140
|
+
|
|
141
|
+
if (await isGzipData(fileBuffer)) {
|
|
142
|
+
const metadata = await getGzipMetadata(fileBuffer);
|
|
143
|
+
console.log(`Original size: ${metadata.originalSize} bytes`);
|
|
144
|
+
console.log(`Compressed size: ${metadata.compressedSize} bytes`);
|
|
145
|
+
console.log(`Saved: ${metadata.compressionPercentageSaved}%`);
|
|
146
|
+
console.log(`Embedded filename: ${metadata.filename}`);
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
### 2. ZIP Creation Utility (`/zip-create`)
|
|
153
|
+
|
|
154
|
+
Create standard ZIP archives from files, folders, Blobs, and in-memory data.
|
|
155
|
+
|
|
156
|
+
#### Create ZIP from Files and Nested Folders
|
|
157
|
+
|
|
158
|
+
```ts
|
|
159
|
+
import { createZip, createZipBlob } from '@rahul_dadhich15/archive-kit/zip-create';
|
|
160
|
+
|
|
161
|
+
const entries = [
|
|
162
|
+
{ path: 'README.md', data: '# My Project\nCreated in browser.' },
|
|
163
|
+
{ path: 'src/index.js', data: 'console.log("Hello World");' },
|
|
164
|
+
{ path: 'assets/logo.png', data: imageUint8Array },
|
|
165
|
+
{ path: 'empty-folder/', type: 'directory' } // Creates empty directory entry
|
|
166
|
+
];
|
|
167
|
+
|
|
168
|
+
// Asynchronously generates ZIP Uint8Array
|
|
169
|
+
const zipBytes = await createZip(entries, {
|
|
170
|
+
compression: 'deflate', // "deflate" or "store"
|
|
171
|
+
compressionLevel: 6, // 0-9
|
|
172
|
+
comment: 'Created with archive-kit'
|
|
173
|
+
});
|
|
174
|
+
|
|
175
|
+
// Or generate an application/zip Blob ready for download
|
|
176
|
+
const zipBlob = await createZipBlob(entries);
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
#### Create ZIP Directly from Browser `<input type="file">`
|
|
180
|
+
|
|
181
|
+
Supports single files, multiple files, and full folder uploads (`webkitdirectory`):
|
|
182
|
+
|
|
183
|
+
```ts
|
|
184
|
+
import { createZipFromFiles } from '@rahul_dadhich15/archive-kit/zip-create';
|
|
185
|
+
|
|
186
|
+
const fileInputElement = document.querySelector('input[type="file"]');
|
|
187
|
+
const files = Array.from(fileInputElement.files);
|
|
188
|
+
|
|
189
|
+
// Automatically preserves folder hierarchies via webkitRelativePath
|
|
190
|
+
const zipBlob = await createZipFromFiles(files);
|
|
191
|
+
|
|
192
|
+
// Trigger client download
|
|
193
|
+
const url = URL.createObjectURL(zipBlob);
|
|
194
|
+
const a = document.createElement('a');
|
|
195
|
+
a.href = url;
|
|
196
|
+
a.download = 'archive.zip';
|
|
197
|
+
a.click();
|
|
198
|
+
URL.revokeObjectURL(url);
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
---
|
|
202
|
+
|
|
203
|
+
### 3. ZIP Extraction & Inspection Utility (`/zip-extract`)
|
|
204
|
+
|
|
205
|
+
Inspect and extract ZIP archives locally with strict security controls against malicious files.
|
|
206
|
+
|
|
207
|
+
#### Inspect File List Without Decompressing (`listZipEntries`)
|
|
208
|
+
|
|
209
|
+
Scans only the ZIP Central Directory in memory without allocating decompressed files:
|
|
210
|
+
|
|
211
|
+
```ts
|
|
212
|
+
import { listZipEntries } from '@rahul_dadhich15/archive-kit/zip-extract';
|
|
213
|
+
|
|
214
|
+
const entries = await listZipEntries(zipFile);
|
|
215
|
+
|
|
216
|
+
for (const entry of entries) {
|
|
217
|
+
console.log(`File: ${entry.path}`);
|
|
218
|
+
console.log(`Compressed: ${entry.compressedSize} B`);
|
|
219
|
+
console.log(`Uncompressed: ${entry.uncompressedSize} B`);
|
|
220
|
+
console.log(`Is Directory: ${entry.isDirectory}`);
|
|
221
|
+
console.log(`Method: ${entry.compressionMethod === 8 ? 'DEFLATE' : 'STORE'}`);
|
|
222
|
+
}
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
#### Extract Entire Archive
|
|
226
|
+
|
|
227
|
+
```ts
|
|
228
|
+
import { extractZip } from '@rahul_dadhich15/archive-kit/zip-extract';
|
|
229
|
+
|
|
230
|
+
const archive = await extractZip(zipData, {
|
|
231
|
+
maxEntries: 5000,
|
|
232
|
+
maxTotalSize: 500 * 1024 * 1024 // 500 MB max total decompressed size
|
|
233
|
+
});
|
|
234
|
+
|
|
235
|
+
console.log(`Extracted ${archive.totalFiles} files and ${archive.totalDirectories} directories.`);
|
|
236
|
+
|
|
237
|
+
for (const entry of archive.entries) {
|
|
238
|
+
if (entry.isDirectory) continue;
|
|
239
|
+
|
|
240
|
+
// Convenient helper methods:
|
|
241
|
+
const textContent = entry.text(); // Decode as UTF-8 string
|
|
242
|
+
const blob = entry.blob('image/png'); // Wrap in Blob for browser display/download
|
|
243
|
+
const rawBytes = entry.data; // Raw Uint8Array
|
|
244
|
+
}
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
#### Selective Extraction (`extractZipEntry`)
|
|
248
|
+
|
|
249
|
+
Decompress only the single requested file while skipping all other entries:
|
|
250
|
+
|
|
251
|
+
```ts
|
|
252
|
+
import { extractZipEntry } from '@rahul_dadhich15/archive-kit/zip-extract';
|
|
253
|
+
|
|
254
|
+
// Only decompresses "documents/report.pdf", leaving all other files compressed
|
|
255
|
+
const entry = await extractZipEntry(zipData, 'documents/report.pdf');
|
|
256
|
+
const pdfBlob = entry.blob('application/pdf');
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
#### Archive Validation & Integrity Check
|
|
260
|
+
|
|
261
|
+
```ts
|
|
262
|
+
import { validateZipArchive } from '@rahul_dadhich15/archive-kit/zip-extract';
|
|
263
|
+
|
|
264
|
+
const verdict = await validateZipArchive(userProvidedBuffer);
|
|
265
|
+
|
|
266
|
+
if (!verdict.valid) {
|
|
267
|
+
console.error('Archive rejected:', verdict.errors);
|
|
268
|
+
} else {
|
|
269
|
+
console.log(`Valid archive containing ${verdict.entryCount} entries.`);
|
|
270
|
+
}
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
---
|
|
274
|
+
|
|
275
|
+
## Security Safeguards
|
|
276
|
+
|
|
277
|
+
Processing untrusted user archives in the client introduces risks that `archive-kit` defends against by default:
|
|
278
|
+
|
|
279
|
+
| Security Threat | Mitigation in `archive-kit` | Error Emitted |
|
|
280
|
+
| :--- | :--- | :--- |
|
|
281
|
+
| **Zip Slip / Path Traversal** | Rejects `..` path traversal, absolute paths (`/`), Windows drive paths (`C:`), UNC paths (`//`), and NUL bytes (`\0`). | `INVALID_ARCHIVE_PATH` |
|
|
282
|
+
| **Decompression Bombs (Zip Bombs)** | Enforces live aggregate byte limits and validates compression ratios (default maximum ratio 100:1). | `COMPRESSION_RATIO_LIMIT_EXCEEDED` / `TOTAL_SIZE_LIMIT_EXCEEDED` |
|
|
283
|
+
| **Oversized Entries** | Enforces per-entry decompressed size ceiling (default 250 MB). | `FILE_SIZE_LIMIT_EXCEEDED` |
|
|
284
|
+
| **Excessive Entry Counts** | Limits maximum archive entries (default 10,000 entries). | `ENTRY_LIMIT_EXCEEDED` |
|
|
285
|
+
| **Data Corruption** | Verifies 32-bit CRC checksums and GZIP ISIZE against decompressed buffers. | `DECOMPRESSION_FAILED` |
|
|
286
|
+
| **Unsupported Encryption** | Rejects password-protected or AES-encrypted entries rather than returning corrupted plaintext. | `UNSUPPORTED_ENCRYPTION` |
|
|
287
|
+
| **Arbitrary Code Execution** | Operates strictly in memory; never executes extracted scripts or writes to the OS filesystem. | N/A |
|
|
288
|
+
|
|
289
|
+
### Customizing Security Limits
|
|
290
|
+
|
|
291
|
+
All limits can be adjusted to match your application's constraints:
|
|
292
|
+
|
|
293
|
+
```ts
|
|
294
|
+
const archive = await extractZip(zipData, {
|
|
295
|
+
maxEntries: 1_000, // Max allowed entries
|
|
296
|
+
maxEntrySize: 50 * 1024 * 1024, // 50 MB max per file
|
|
297
|
+
maxTotalSize: 200 * 1024 * 1024, // 200 MB max aggregate decompressed size
|
|
298
|
+
maxCompressionRatio: 50 // Reject if ratio > 50:1
|
|
299
|
+
});
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
---
|
|
303
|
+
|
|
304
|
+
## Synchronous APIs
|
|
305
|
+
|
|
306
|
+
For small in-memory operations where an asynchronous Promise is unnecessary, synchronous equivalents are provided:
|
|
307
|
+
|
|
308
|
+
- `gzipCompressSync(data, options?)`
|
|
309
|
+
- `gzipDecompressSync(data, options?)`
|
|
310
|
+
- `gzipCompressTextSync(text, options?)`
|
|
311
|
+
- `gzipDecompressTextSync(data, options?)`
|
|
312
|
+
- `isGzipDataSync(data)`
|
|
313
|
+
- `getGzipMetadataSync(data)`
|
|
314
|
+
- `createZipSync(entries, options?)`
|
|
315
|
+
- `isZipArchiveSync(data)`
|
|
316
|
+
|
|
317
|
+
> **Warning**: Synchronous APIs run on the JavaScript main thread. For larger files (>5 MB) in browser applications, always use the asynchronous APIs to avoid UI freezes.
|
|
318
|
+
|
|
319
|
+
---
|
|
320
|
+
|
|
321
|
+
## Cancellation Support
|
|
322
|
+
|
|
323
|
+
All asynchronous operations accept an optional `AbortSignal`:
|
|
324
|
+
|
|
325
|
+
```ts
|
|
326
|
+
const controller = new AbortController();
|
|
327
|
+
|
|
328
|
+
// Cancel when user clicks "Cancel" in your React UI
|
|
329
|
+
cancelButton.addEventListener('click', () => controller.abort());
|
|
330
|
+
|
|
331
|
+
try {
|
|
332
|
+
const result = await createZip(largeFileList, { signal: controller.signal });
|
|
333
|
+
} catch (err) {
|
|
334
|
+
if (err.code === 'OPERATION_CANCELLED') {
|
|
335
|
+
console.log('User cancelled archive creation');
|
|
336
|
+
}
|
|
337
|
+
}
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
---
|
|
341
|
+
|
|
342
|
+
## Known Limitations
|
|
343
|
+
|
|
344
|
+
- **Compression Methods**: Supports standard ZIP **STORE** (`0`) and **DEFLATE** (`8`). Proprietary or legacy algorithms (e.g. BZIP2, LZMA, PPMd, Zstandard) are rejected with `UNSUPPORTED_COMPRESSION`.
|
|
345
|
+
- **Encryption**: Password-protected and AES-encrypted archives are not supported and are safely rejected with `UNSUPPORTED_ENCRYPTION`.
|
|
346
|
+
- **Archive Size**: Standard ZIP format supports archives up to 4 GB (2^32 bytes). ZIP64 extensions and multi-volume spanned archives are not supported.
|
|
347
|
+
- **Browser Memory Limits**: All processing takes place within browser tab memory (ArrayBuffers and Blobs). Modern browser tabs typically handle archives up to 500 MB – 1 GB before encountering V8 heap exhaustion.
|
|
348
|
+
|
|
349
|
+
---
|
|
350
|
+
|
|
351
|
+
## Development & Testing
|
|
352
|
+
|
|
353
|
+
```bash
|
|
354
|
+
# Install dependencies
|
|
355
|
+
npm install
|
|
356
|
+
|
|
357
|
+
# Run TypeScript typecheck
|
|
358
|
+
npm run typecheck
|
|
359
|
+
|
|
360
|
+
# Run ESLint
|
|
361
|
+
npm run lint
|
|
362
|
+
|
|
363
|
+
# Run Vitest unit, integration, and security tests
|
|
364
|
+
npm run test
|
|
365
|
+
|
|
366
|
+
# Run test coverage audit (enforces 90% lines/statements, 80% branches)
|
|
367
|
+
npm run test:coverage
|
|
368
|
+
|
|
369
|
+
# Run real-browser Playwright tests in headless Chromium
|
|
370
|
+
npm run test:browser
|
|
371
|
+
|
|
372
|
+
# Run smoke test on built artifacts
|
|
373
|
+
npm run test:smoke
|
|
374
|
+
|
|
375
|
+
# Run full consumer sandbox verification pipeline
|
|
376
|
+
npm run test:consumer
|
|
377
|
+
|
|
378
|
+
# Build production distribution
|
|
379
|
+
npm run build
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
---
|
|
383
|
+
|
|
384
|
+
## License
|
|
385
|
+
|
|
386
|
+
[MIT](LICENSE) © 2026 Rahul Dadhich
|