0
# @zip.js/zip.js
1
2
## Package Information
3
4
- **Package Name:** @zip.js/zip.js
5
- **Type:** Library
6
- **Language:** JavaScript/TypeScript
7
- **Installation:** `npm install @zip.js/zip.js`
8
9
## Overview
10
11
zip.js is a powerful JavaScript library for creating and reading ZIP files in browsers, Deno, and Node.js environments. It provides a comprehensive set of APIs for ZIP file manipulation with support for advanced features and optimal performance across different JavaScript runtime environments.
12
13
### Key Features
14
15
- **Multi-core compression** via web workers for improved performance
16
- **Large file support** with Zip64 format (files > 4GB)
17
- **Data encryption** using AES-256, AES-192, AES-128, and ZipCrypto algorithms
18
- **Split ZIP files** for handling size-constrained storage
19
- **Streaming operations** for memory-efficient processing of large archives
20
- **Multiple data sources** including Blob, ArrayBuffer, ReadableStream, HTTP ranges
21
- **Filesystem-like API** for complex ZIP manipulation scenarios
22
- **Native compression streams** support for optimal performance
23
- **Cross-platform compatibility** (browsers, Node.js, Deno, Bun)
24
25
## Core Imports
26
27
### ESM (Recommended)
28
29
```javascript
30
import {
31
ZipReader,
32
ZipWriter,
33
BlobReader,
34
BlobWriter,
35
TextReader,
36
TextWriter,
37
configure
38
} from "@zip.js/zip.js";
39
```
40
41
### CommonJS
42
43
```javascript
44
const {
45
ZipReader,
46
ZipWriter,
47
BlobReader,
48
BlobWriter,
49
TextReader,
50
TextWriter,
51
configure
52
} = require("@zip.js/zip.js");
53
```
54
55
### Alternative Entry Points
56
57
```javascript
58
// Full API with embedded codecs
59
import * as zip from "@zip.js/zip.js/lib/zip-full.js";
60
61
// Filesystem API
62
import { fs } from "@zip.js/zip.js/lib/zip-fs.js";
63
64
// No web workers
65
import * as zip from "@zip.js/zip.js/lib/zip-no-worker.js";
66
```
67
68
## Basic Usage
69
70
```javascript
71
import {
72
ZipReader,
73
ZipWriter,
74
BlobReader,
75
BlobWriter,
76
TextReader,
77
TextWriter
78
} from "@zip.js/zip.js";
79
80
// Create a ZIP file
81
const zipWriter = new ZipWriter(new BlobWriter("application/zip"));
82
await zipWriter.add("hello.txt", new TextReader("Hello World!"));
83
const zipBlob = await zipWriter.close();
84
85
// Read a ZIP file
86
const zipReader = new ZipReader(new BlobReader(zipBlob));
87
const entries = await zipReader.getEntries();
88
const text = await entries[0].getData(new TextWriter());
89
await zipReader.close();
90
console.log(text); // "Hello World!"
91
```
92
93
## Architecture
94
95
zip.js is designed with a modular architecture supporting different use cases and environments while maintaining optimal performance and memory efficiency.
96
97
### Core Components
98
99
**Core API (`@zip.js/zip.js`)**
100
- `ZipReader`/`ZipWriter` - Primary classes for ZIP operations
101
- Reader/Writer abstraction for different data sources/destinations
102
- Configurable web worker support for non-blocking operations
103
104
**Streaming API**
105
- `ZipReaderStream`/`ZipWriterStream` - Stream-based processing
106
- Memory-efficient handling of large files
107
- Pipeline-compatible with web streams
108
109
**Filesystem API (`@zip.js/zip.js/lib/zip-fs.js`)**
110
- `FS` class providing filesystem-like operations
111
- `ZipDirectoryEntry`/`ZipFileEntry` for hierarchical manipulation
112
- Import/export capabilities with multiple data formats
113
114
### Build Variants
115
116
- **Default build**: Web workers + compression streams
117
- **Full build** (`zip-full.js`): Embedded codecs, no external dependencies
118
- **No-worker builds**: Synchronous operation variants
119
- **Filesystem build** (`zip-fs.js`): High-level filesystem API
120
121
### Web Worker Architecture
122
123
zip.js uses web workers for non-blocking compression/decompression:
124
- Automatic worker management and load balancing
125
- Configurable worker count and termination timeout
126
- Fallback to main thread when workers unavailable
127
128
## Configuration
129
130
Global library configuration for web workers, compression, and codecs.
131
132
```typescript { .api }
133
function configure(configuration: Configuration): void;
134
135
interface Configuration extends WorkerConfiguration {
136
maxWorkers?: number;
137
terminateWorkerTimeout?: number;
138
workerScripts?: {
139
deflate?: string[];
140
inflate?: string[];
141
};
142
chunkSize?: number;
143
Deflate?: typeof ZipDeflate;
144
Inflate?: typeof ZipInflate;
145
CompressionStream?: typeof TransformStream;
146
DecompressionStream?: typeof TransformStream;
147
}
148
149
interface WorkerConfiguration {
150
useWebWorkers?: boolean;
151
useCompressionStream?: boolean;
152
}
153
```
154
155
**[Configuration Details](./configuration.md)**
156
157
## Data Input/Output
158
159
Classes for reading from and writing to different data sources and destinations.
160
161
### Reader Classes
162
163
```typescript { .api }
164
class Reader<Type> {
165
constructor(value: Type);
166
readonly readable: ReadableStream;
167
readonly size: number;
168
init?(): Promise<void>;
169
readUint8Array(index: number, length: number): Promise<Uint8Array>;
170
}
171
172
class TextReader extends Reader<string> {}
173
class BlobReader extends Reader<Blob> {}
174
class Data64URIReader extends Reader<string> {}
175
class Uint8ArrayReader extends Reader<Uint8Array> {}
176
class HttpReader extends Reader<string> {
177
constructor(url: string | URL, options?: HttpOptions);
178
}
179
class HttpRangeReader extends HttpReader {
180
constructor(url: string | URL, options?: HttpRangeOptions);
181
}
182
class SplitDataReader extends Reader<(Reader<unknown> | ReadableReader | ReadableStream)[]> {}
183
```
184
185
### Writer Classes
186
187
```typescript { .api }
188
class Writer<Type> {
189
readonly writable: WritableStream;
190
init?(size?: number): Promise<void>;
191
writeUint8Array(array: Uint8Array): Promise<void>;
192
getData(): Promise<Type>;
193
}
194
195
class TextWriter extends Writer<string> {
196
constructor(encoding?: string);
197
}
198
class BlobWriter {
199
constructor(mimeString?: string);
200
readonly writable: WritableStream;
201
init(): Promise<void>;
202
getData(): Promise<Blob>;
203
}
204
class Data64URIWriter extends Writer<string> {
205
constructor(mimeString?: string);
206
}
207
class Uint8ArrayWriter extends Writer<Uint8Array> {}
208
class SplitDataWriter {
209
constructor(
210
writerGenerator: AsyncGenerator<Writer<unknown> | WritableWriter | WritableStream, boolean>,
211
maxSize?: number
212
);
213
readonly writable: WritableStream;
214
init(): Promise<void>;
215
}
216
```
217
218
**[Data Input/Output Details](./data-io.md)**
219
220
## ZIP Reading
221
222
Reading and extracting from ZIP files.
223
224
```typescript { .api }
225
class ZipReader<Type> {
226
constructor(
227
reader: Reader<Type> | ReadableReader | ReadableStream | (Reader<unknown> | ReadableReader | ReadableStream)[],
228
options?: ZipReaderConstructorOptions
229
);
230
231
readonly comment: Uint8Array;
232
readonly prependedData?: Uint8Array;
233
readonly appendedData?: Uint8Array;
234
235
getEntries(options?: ZipReaderGetEntriesOptions): Promise<Entry[]>;
236
getEntriesGenerator(options?: ZipReaderGetEntriesOptions): AsyncGenerator<Entry, boolean>;
237
close(): Promise<void>;
238
}
239
240
type Entry = DirectoryEntry | FileEntry;
241
242
interface DirectoryEntry extends EntryMetaData {
243
directory: true;
244
getData?: undefined;
245
}
246
247
interface FileEntry extends EntryMetaData {
248
directory: false;
249
getData<Type>(
250
writer: Writer<Type> | WritableWriter | WritableStream | AsyncGenerator<Writer<unknown> | WritableWriter | WritableStream, boolean>,
251
options?: EntryGetDataOptions
252
): Promise<Type>;
253
arrayBuffer(options?: EntryGetDataOptions): Promise<ArrayBuffer>;
254
}
255
```
256
257
**[ZIP Reading Details](./reading.md)**
258
259
## ZIP Writing
260
261
Creating and modifying ZIP files.
262
263
```typescript { .api }
264
class ZipWriter<Type> {
265
constructor(
266
writer: Writer<Type> | WritableWriter | WritableStream | AsyncGenerator<Writer<unknown> | WritableWriter | WritableStream, boolean>,
267
options?: ZipWriterConstructorOptions
268
);
269
270
readonly hasCorruptedEntries?: boolean;
271
272
prependZip<ReaderType>(
273
reader: Reader<ReaderType> | ReadableReader | ReadableStream | (Reader<unknown> | ReadableReader | ReadableStream)[]
274
): Promise<void>;
275
276
add<ReaderType>(
277
filename: string,
278
reader?: Reader<ReaderType> | ReadableReader | ReadableStream | (Reader<unknown> | ReadableReader | ReadableStream)[],
279
options?: ZipWriterAddDataOptions
280
): Promise<EntryMetaData>;
281
282
remove(entry: Entry | string): boolean;
283
close(comment?: Uint8Array, options?: ZipWriterCloseOptions): Promise<Type>;
284
}
285
```
286
287
**[ZIP Writing Details](./writing.md)**
288
289
## Streaming API
290
291
Stream-based ZIP operations for efficient processing of large files.
292
293
```typescript { .api }
294
class ZipReaderStream<T> {
295
constructor(options?: ZipReaderConstructorOptions);
296
297
readonly readable: ReadableStream<Omit<Entry, "getData"> & { readable?: ReadableStream<Uint8Array> }>;
298
readonly writable: WritableStream<T>;
299
}
300
301
class ZipWriterStream {
302
constructor(options?: ZipWriterConstructorOptions);
303
304
readonly readable: ReadableStream<Uint8Array>;
305
readonly zipWriter: ZipWriter<unknown>;
306
307
transform<T>(path: string): { readable: ReadableStream<T>; writable: WritableStream<T> };
308
writable<T>(path: string): WritableStream<T>;
309
close(comment?: Uint8Array, options?: ZipWriterCloseOptions): Promise<unknown>;
310
}
311
```
312
313
**[Streaming API Details](./streaming.md)**
314
315
## Filesystem API
316
317
High-level filesystem-like operations for complex ZIP manipulation.
318
319
```typescript { .api }
320
const fs: {
321
FS: typeof FS;
322
ZipDirectoryEntry: typeof ZipDirectoryEntry;
323
ZipFileEntry: typeof ZipFileEntry;
324
};
325
326
class FS extends ZipDirectoryEntry {
327
readonly root: ZipDirectoryEntry;
328
329
remove(entry: ZipEntry): void;
330
move(entry: ZipEntry, destination: ZipDirectoryEntry): void;
331
find(fullname: string): ZipEntry | undefined;
332
getById(id: number): ZipEntry | undefined;
333
}
334
```
335
336
**[Filesystem API Details](./filesystem.md)**
337
338
## Utilities
339
340
```typescript { .api }
341
function getMimeType(fileExtension: string): string;
342
function terminateWorkers(): Promise<void>;
343
function initShimAsyncCodec(
344
library: EventBasedZipLibrary,
345
constructorOptions: unknown | null,
346
registerDataHandler: registerDataHandler
347
): ZipLibrary;
348
```
349
350
## Error Constants
351
352
```typescript { .api }
353
const ERR_HTTP_RANGE: string;
354
const ERR_BAD_FORMAT: string;
355
const ERR_EOCDR_NOT_FOUND: string;
356
const ERR_EOCDR_LOCATOR_ZIP64_NOT_FOUND: string;
357
const ERR_CENTRAL_DIRECTORY_NOT_FOUND: string;
358
const ERR_LOCAL_FILE_HEADER_NOT_FOUND: string;
359
const ERR_EXTRAFIELD_ZIP64_NOT_FOUND: string;
360
const ERR_ENCRYPTED: string;
361
const ERR_UNSUPPORTED_ENCRYPTION: string;
362
const ERR_UNSUPPORTED_COMPRESSION: string;
363
const ERR_INVALID_SIGNATURE: string;
364
const ERR_INVALID_UNCOMPRESSED_SIZE: string;
365
const ERR_INVALID_PASSWORD: string;
366
const ERR_DUPLICATED_NAME: string;
367
const ERR_INVALID_COMMENT: string;
368
const ERR_INVALID_ENTRY_NAME: string;
369
const ERR_INVALID_ENTRY_COMMENT: string;
370
const ERR_INVALID_VERSION: string;
371
const ERR_INVALID_EXTRAFIELD_TYPE: string;
372
const ERR_INVALID_EXTRAFIELD_DATA: string;
373
const ERR_INVALID_ENCRYPTION_STRENGTH: string;
374
const ERR_UNSUPPORTED_FORMAT: string;
375
const ERR_SPLIT_ZIP_FILE: string;
376
const ERR_OVERLAPPING_ENTRY: string;
377
const ERR_ITERATOR_COMPLETED_TOO_SOON: string;
378
const ERR_UNDEFINED_UNCOMPRESSED_SIZE: string;
379
const ERR_WRITER_NOT_INITIALIZED: string;
380
const ERR_ZIP_NOT_EMPTY: string;
381
```
382
383
## Types
384
385
### EntryMetaData
386
387
```typescript { .api }
388
interface EntryMetaData {
389
offset: number;
390
filename: string;
391
rawFilename: Uint8Array;
392
filenameUTF8: boolean;
393
directory: boolean;
394
executable: boolean;
395
encrypted: boolean;
396
zipCrypto: boolean;
397
compressedSize: number;
398
uncompressedSize: number;
399
lastModDate: Date;
400
lastAccessDate?: Date;
401
creationDate?: Date;
402
rawLastModDate: number | bigint;
403
rawLastAccessDate?: number | bigint;
404
rawCreationDate?: number | bigint;
405
comment: string;
406
rawComment: Uint8Array;
407
commentUTF8: boolean;
408
signature: number;
409
extraField?: Map<number, { type: number; data: Uint8Array }>;
410
rawExtraField: Uint8Array;
411
zip64: boolean;
412
version: number;
413
versionMadeBy: number;
414
msDosCompatible: boolean;
415
internalFileAttributes: number;
416
externalFileAttributes: number;
417
diskNumberStart: number;
418
compressionMethod: number;
419
}
420
```
421
422
### HTTP Options
423
424
```typescript { .api }
425
interface HttpOptions extends HttpRangeOptions {
426
useRangeHeader?: boolean;
427
forceRangeRequests?: boolean;
428
preventHeadRequest?: boolean;
429
combineSizeEocd?: boolean;
430
}
431
432
interface HttpRangeOptions {
433
useXHR?: boolean;
434
headers?: Iterable<[string, string]> | Map<string, string>;
435
}
436
```
437
438
### Reader/Writer Interfaces
439
440
```typescript { .api }
441
interface Initializable {
442
init?(): Promise<void>;
443
}
444
445
interface ReadableReader {
446
readable: ReadableStream;
447
}
448
449
interface WritableWriter {
450
writable: WritableStream;
451
maxSize?: number;
452
}
453
```
454
455
### Event-based Codec Interfaces
456
457
```typescript { .api }
458
interface EventBasedZipLibrary {
459
Deflate: typeof EventBasedCodec;
460
Inflate: typeof EventBasedCodec;
461
}
462
463
interface ZipLibrary {
464
Deflate: typeof ZipDeflate;
465
Inflate: typeof ZipInflate;
466
}
467
468
interface registerDataHandler {
469
(codec: EventBasedCodec, onData: dataHandler): void;
470
}
471
472
interface dataHandler {
473
(data: Uint8Array): void;
474
}
475
```
476
477
### Option Interfaces
478
479
```typescript { .api }
480
interface ZipReaderConstructorOptions extends ZipReaderOptions, GetEntriesOptions, WorkerConfiguration {
481
extractPrependedData?: boolean;
482
extractAppendedData?: boolean;
483
}
484
485
interface ZipReaderGetEntriesOptions extends GetEntriesOptions, EntryOnprogressOptions {}
486
487
interface GetEntriesOptions {
488
filenameEncoding?: string;
489
commentEncoding?: string;
490
decodeText?(value: Uint8Array, encoding: string): string | undefined;
491
}
492
493
interface ZipReaderOptions {
494
checkPasswordOnly?: boolean;
495
checkSignature?: boolean;
496
checkOverlappingEntry?: boolean;
497
checkOverlappingEntryOnly?: boolean;
498
password?: string;
499
passThrough?: boolean;
500
rawPassword?: Uint8Array;
501
signal?: AbortSignal;
502
preventClose?: boolean;
503
transferStreams?: boolean;
504
}
505
506
interface EntryGetDataOptions extends EntryDataOnprogressOptions, ZipReaderOptions, WorkerConfiguration {}
507
508
interface ZipWriterConstructorOptions {
509
zip64?: boolean;
510
preventClose?: boolean;
511
level?: number;
512
bufferedWrite?: boolean;
513
keepOrder?: boolean;
514
password?: string;
515
rawPassword?: Uint8Array;
516
encryptionStrength?: 1 | 2 | 3;
517
signal?: AbortSignal;
518
lastModDate?: Date;
519
lastAccessDate?: Date;
520
creationDate?: Date;
521
extendedTimestamp?: boolean;
522
zipCrypto?: boolean;
523
version?: number;
524
versionMadeBy?: number;
525
useUnicodeFileNames?: boolean;
526
dataDescriptor?: boolean;
527
dataDescriptorSignature?: boolean;
528
msDosCompatible?: boolean;
529
externalFileAttributes?: number;
530
internalFileAttributes?: number;
531
supportZip64SplitFile?: boolean;
532
usdz?: boolean;
533
passThrough?: boolean;
534
encrypted?: boolean;
535
offset?: number;
536
compressionMethod?: number;
537
encodeText?(text: string): Uint8Array | undefined;
538
}
539
540
interface ZipWriterAddDataOptions extends ZipWriterConstructorOptions, EntryDataOnprogressOptions, WorkerConfiguration {
541
directory?: boolean;
542
executable?: boolean;
543
comment?: string;
544
extraField?: Map<number, Uint8Array>;
545
uncompressedSize?: number;
546
signature?: number;
547
}
548
549
interface ZipWriterCloseOptions extends EntryOnprogressOptions {
550
zip64?: boolean;
551
preventClose?: boolean;
552
}
553
554
interface EntryDataOnprogressOptions {
555
onstart?(total: number): Promise<void> | undefined;
556
onprogress?(progress: number, total: number): Promise<void> | undefined;
557
onend?(computedSize: number): Promise<void> | undefined;
558
}
559
560
interface EntryOnprogressOptions {
561
onprogress?(progress: number, total: number, entry: EntryMetaData): Promise<void> | undefined;
562
}
563
564
declare class SyncCodec {
565
append(data: Uint8Array): Uint8Array;
566
}
567
568
declare class ZipDeflate extends SyncCodec {
569
flush(): Uint8Array;
570
}
571
572
declare class ZipInflate extends SyncCodec {
573
flush(): void;
574
}
575
576
declare class EventBasedCodec {
577
push(data: Uint8Array): void;
578
ondata(data?: Uint8Array): void;
579
}
580
```