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
```