0
# @yarnpkg/libzip
1
2
@yarnpkg/libzip is a WebAssembly-compiled version of the libzip C library that provides ZIP archive manipulation capabilities for JavaScript and TypeScript applications. It offers both synchronous and asynchronous APIs for creating, reading, and modifying ZIP files, with specialized exports for browser and Node.js environments.
3
4
## Package Information
5
6
- **Package Name**: @yarnpkg/libzip
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @yarnpkg/libzip`
10
11
## Core Imports
12
13
For Node.js (synchronous API):
14
15
```typescript
16
import { ZipFS, ZipOpenFS, getLibzipSync, mountMemoryDrive } from "@yarnpkg/libzip";
17
```
18
19
For browsers (asynchronous API):
20
21
```typescript
22
import { ZipFS, ZipOpenFS, getLibzipPromise, mountMemoryDrive } from "@yarnpkg/libzip";
23
```
24
25
CommonJS:
26
27
```javascript
28
const { ZipFS, ZipOpenFS, getLibzipSync, mountMemoryDrive } = require("@yarnpkg/libzip");
29
```
30
31
## Basic Usage
32
33
```typescript
34
import { ZipFS, ZipOpenFS, getLibzipSync } from "@yarnpkg/libzip";
35
import { ppath } from "@yarnpkg/fslib";
36
37
// High-level filesystem approach with ZipFS
38
const zipFs = new ZipFS("/path/to/archive.zip" as ppath.PortablePath, {
39
create: true
40
});
41
42
// Write files to the ZIP archive
43
zipFs.writeFileSync("/hello.txt" as ppath.PortablePath, "Hello, World!");
44
zipFs.mkdirSync("/documents" as ppath.PortablePath);
45
zipFs.writeFileSync("/documents/readme.md" as ppath.PortablePath, "# Readme");
46
47
// Read files from the ZIP archive
48
const content = zipFs.readFileSync("/hello.txt" as ppath.PortablePath, "utf8");
49
const files = zipFs.readdirSync("/" as ppath.PortablePath);
50
51
// Automatic ZIP mounting with ZipOpenFS
52
const zipOpenFs = new ZipOpenFS();
53
const stat = zipOpenFs.statSync("/path/to/archive.zip/inner/file.txt" as ppath.PortablePath);
54
55
// Low-level libzip access
56
const libzip = getLibzipSync();
57
// Use libzip.* methods for direct ZIP manipulation
58
```
59
60
## Architecture
61
62
@yarnpkg/libzip is built around several key components:
63
64
- **WebAssembly Core**: Emscripten-compiled libzip C library providing native ZIP functionality
65
- **High-level API**: `ZipFS` and `ZipOpenFS` classes implementing familiar filesystem interfaces
66
- **Dual Entry Points**: Synchronous (Node.js) and asynchronous (browser) module loading
67
- **Implementation Flexibility**: Multiple ZIP implementations (`LibZipImpl`, `JsZipImpl`) for different use cases
68
- **Memory Management**: Direct memory access and buffer manipulation for performance
69
70
## Capabilities
71
72
### Filesystem Operations
73
74
High-level filesystem interface for ZIP archives supporting standard file operations like read, write, mkdir, and stat. Integrates seamlessly with the Yarn package manager ecosystem.
75
76
```typescript { .api }
77
class ZipFS extends BasePortableFakeFS {
78
constructor(source: PortablePath | Buffer, options?: ZipBufferOptions | ZipPathOptions);
79
80
readFileSync(p: PortablePath, encoding?: BufferEncoding): string | Buffer;
81
writeFileSync(p: PortablePath, data: string | Buffer): void;
82
mkdirSync(p: PortablePath, options?: MkdirOptions): void;
83
statSync(p: PortablePath): Stats;
84
readdirSync(p: PortablePath): string[];
85
}
86
87
class ZipOpenFS extends MountFS<ZipFS> {
88
constructor(opts?: ZipOpenFSOptions);
89
static openPromise<T>(fn: (zipOpenFs: ZipOpenFS) => Promise<T>, opts?: ZipOpenFSOptions): Promise<T>;
90
}
91
```
92
93
[Filesystem Operations](./filesystem.md)
94
95
### Low-level Libzip Interface
96
97
Direct access to the WebAssembly-compiled libzip C library for advanced ZIP manipulation and fine-grained control over archive operations.
98
99
```typescript { .api }
100
function getLibzipSync(): Libzip;
101
function getLibzipPromise(): Promise<Libzip>;
102
103
interface Libzip {
104
// Memory management
105
HEAPU8: Uint8Array;
106
malloc(size: number): number;
107
free(ptr: number): void;
108
109
// Archive operations
110
openFromSource(source: number, flags: number, error: number): number;
111
close(archive: number): number;
112
getNumEntries(archive: number, flags: number): number;
113
getName(archive: number, index: number, flags: number): string;
114
}
115
```
116
117
[Low-level Libzip Interface](./libzip-interface.md)
118
119
### ZIP Implementation Classes
120
121
Pluggable ZIP implementations providing different performance and compatibility characteristics for various environments and use cases.
122
123
```typescript { .api }
124
class LibZipImpl implements ZipImpl {
125
constructor(opts: ZipImplInput);
126
getFileSource(index: number): {data: Buffer, compressionMethod: number};
127
setFileSource(target: PortablePath, compression: CompressionData, buffer: Buffer): number;
128
}
129
130
class JsZipImpl implements ZipImpl {
131
constructor(opts: ZipImplInput);
132
// Read-only pure JavaScript implementation
133
}
134
```
135
136
[Implementation Classes](./implementations.md)
137
138
### Utility Functions
139
140
Helper functions for memory mounting, archive creation, and path manipulation to support common ZIP operations and integration patterns.
141
142
```typescript { .api }
143
function mountMemoryDrive(
144
origFs: typeof fs,
145
mountPoint: PortablePath,
146
source?: Buffer | null,
147
opts?: MemoryDriveOpts
148
): ZipFS;
149
150
function makeEmptyArchive(): Buffer;
151
152
function getArchivePart(path: string, extension: string): PortablePath | null;
153
```
154
155
[Utility Functions](./utilities.md)
156
157
## Types
158
159
```typescript { .api }
160
type ZipCompression = "mixed" | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
161
type CompressionData = [compressionMethod: number, level: number] | null;
162
163
interface ZipBufferOptions {
164
customZipImplementation?: ZipImplementationClass;
165
readOnly?: boolean;
166
stats?: Stats;
167
level?: ZipCompression;
168
}
169
170
interface ZipPathOptions extends ZipBufferOptions {
171
baseFs?: FakeFS<PortablePath>;
172
create?: boolean;
173
}
174
175
interface ZipOpenFSOptions {
176
libzip?: Libzip | (() => Libzip);
177
readOnlyArchives?: boolean;
178
customZipImplementation?: ZipImplementationClass;
179
fileExtensions?: Array<string> | null;
180
}
181
182
interface MemoryDriveOpts {
183
typeCheck?: number | null;
184
}
185
186
enum Errors {
187
ZIP_ER_OK = 0,
188
ZIP_ER_MULTIDISK = 1,
189
ZIP_ER_RENAME = 2,
190
// ... 30 additional error codes
191
}
192
```