@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 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
- # Temporary Holding Version
1
+ # @rahul_dadhich15/archive-kit
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![CI](https://github.com/rahuldadhich1517-sys/archive-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/rahuldadhich1517-sys/archive-kit/actions/workflows/ci.yml)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
5
+ [![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue.svg)](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