0
# Low-level Libzip Interface
1

2
Direct access to the WebAssembly-compiled libzip C library for advanced ZIP manipulation and fine-grained control over archive operations. This interface provides the raw libzip functionality with minimal JavaScript wrapper overhead.
3

4
## Capabilities
5

6
### Libzip Instance Access
7

8
Get access to the compiled libzip WebAssembly module for direct manipulation.
9

10
```typescript { .api }
11
/**
12
 * Get synchronous libzip instance (Node.js)
13
 * @returns The libzip interface instance
14
 */
15
function getLibzipSync(): Libzip;
16

17
/**
18
 * Get asynchronous libzip instance (Browser)
19
 * @returns Promise resolving to the libzip interface instance
20
 */
21
function getLibzipPromise(): Promise<Libzip>;
22
```
23

24
**Usage Examples:**
25

26
```typescript
27
import { getLibzipSync, getLibzipPromise } from "@yarnpkg/libzip";
28

29
// Node.js synchronous usage
30
const libzip = getLibzipSync();
31
const archive = libzip.openFromSource(sourcePtr, libzip.ZIP_RDONLY, errorPtr);
32

33
// Browser asynchronous usage
34
const libzip = await getLibzipPromise();
35
const archive = libzip.openFromSource(sourcePtr, libzip.ZIP_RDONLY, errorPtr);
36
```
37

38
### Core Libzip Interface
39

40
The main interface providing direct access to libzip C library functions.
41

42
```typescript { .api }
43
interface Libzip {
44
  // Memory management
45
  readonly HEAPU8: Uint8Array;
46
  malloc(size: number): number;
47
  free(ptr: number): void;
48
  getValue(ptr: number, type: string): number;
49
  
50
  // Error handling
51
  readonly errors: typeof Errors;
52
  
53
  // Constants
54
  readonly SEEK_SET: 0;
55
  readonly SEEK_CUR: 1;
56
  readonly SEEK_END: 2;
57
  
58
  readonly ZIP_CHECKCONS: 4;
59
  readonly ZIP_EXCL: 2;
60
  readonly ZIP_RDONLY: 16;
61
  
62
  readonly ZIP_FL_OVERWRITE: 8192;
63
  readonly ZIP_FL_COMPRESSED: 4;
64
  
65
  // Compression methods
66
  readonly ZIP_CM_DEFAULT: -1;
67
  readonly ZIP_CM_STORE: 0;
68
  readonly ZIP_CM_DEFLATE: 8;
69
  
70
  // Operating system constants
71
  readonly ZIP_OPSYS_DOS: 0x00;
72
  readonly ZIP_OPSYS_UNIX: 0x03;
73
  readonly ZIP_OPSYS_WINDOWS_NTFS: 0x0a;
74
  // ... additional OS constants
75
  
76
  // Archive operations
77
  openFromSource(source: number, flags: number, error: number): number;
78
  close(archive: number): number;
79
  discard(archive: number): void;
80
  getError(archive: number): number;
81
  getName(archive: number, index: number, flags: number): string;
82
  getNumEntries(archive: number, flags: number): number;
83
  
84
  // Entry operations
85
  delete(archive: number, index: number): number;
86
  statIndex(archive: number, indexLow: number, indexHigh: number, flags: number, stat: number): number;
87
  
88
  // File operations
89
  fopenIndex(archive: number, indexLow: number, indexHigh: number, flags: number): number;
90
  fread(file: number, buffer: number, length: number, archive: number): number;
91
  fclose(file: number): number;
92
  
93
  // Directory operations
94
  dir: {
95
    add(archive: number, path: string): number;
96
  };
97
  
98
  // File management
99
  file: {
100
    add(archive: number, path: string, source: number, flags: number): number;
101
    getError(file: number): number;
102
    getExternalAttributes(archive: number, indexLow: number, indexHigh: number, flags: number, opsys: number, attributes: number): number;
103
    setExternalAttributes(archive: number, indexLow: number, indexHigh: number, flags: number, opsys: number, attributes: number): number;
104
    setMtime(archive: number, indexLow: number, indexHigh: number, mtime: number, flags: number): number;
105
    setCompression(archive: number, indexLow: number, indexHigh: number, comp: number, flags: number): number;
106
  };
107
  
108
  // Source management
109
  source: {
110
    fromUnattachedBuffer(buffer: number, sizeLow: number, sizeHigh: number, freep: number, error: number): number;
111
    fromBuffer(archive: number, buffer: number, sizeLow: number, sizeHigh: number, freep: number): number;
112
    free(source: number): void;
113
    keep(source: number): void;
114
    open(source: number): number;
115
    close(source: number): number;
116
    seek(source: number, offsetLow: number, offsetHigh: number, whence: number): number;
117
    tell(source: number): number;
118
    read(source: number, buffer: number, length: number): number;
119
    error(source: number): number;
120
  };
121
  
122
  // Name operations
123
  name: {
124
    locate(archive: number, path: string, flags: number): number;
125
  };
126
  
127
  // Error operations
128
  error: {
129
    initWithCode(error: number, code: number): void;
130
    strerror(error: number): string;
131
  };
132
  
133
  // Extension operations
134
  ext: {
135
    countSymlinks(archive: number): number;
136
  };
137
  
138
  // Structure field accessors
139
  struct: {
140
    statS(): number;
141
    statSize(stat: number): number;
142
    statCompSize(stat: number): number;
143
    statCompMethod(stat: number): number;
144
    statMtime(stat: number): number;
145
    statCrc(stat: number): number;
146
    
147
    errorS(): number;
148
    errorCodeZip(error: number): number;
149
  };
150
}
151
```
152

153
**Usage Examples:**
154

155
```typescript
156
import { getLibzipSync, Errors } from "@yarnpkg/libzip";
157

158
const libzip = getLibzipSync();
159

160
// Create a buffer source
161
const data = Buffer.from("Hello, ZIP!");
162
const bufferPtr = libzip.malloc(data.length);
163
libzip.HEAPU8.set(data, bufferPtr);
164

165
const sourcePtr = libzip.source.fromUnattachedBuffer(
166
  bufferPtr, 
167
  data.length, 
168
  0, // size high (for 64-bit)
169
  0, // freep
170
  0  // error
171
);
172

173
// Create new archive
174
const errorPtr = libzip.malloc(4);
175
const archivePtr = libzip.openFromSource(sourcePtr, 0, errorPtr);
176

177
if (archivePtr === 0) {
178
  const errorCode = libzip.getValue(errorPtr, "i32");
179
  console.error("Failed to create archive:", errorCode);
180
  libzip.free(errorPtr);
181
  return;
182
}
183

184
// Add file to archive
185
const fileSourcePtr = libzip.source.fromBuffer(
186
  archivePtr,
187
  bufferPtr,
188
  data.length,
189
  0,
190
  0
191
);
192

193
libzip.file.add(archivePtr, "hello.txt", fileSourcePtr, 0);
194

195
// Close and cleanup
196
libzip.close(archivePtr);
197
libzip.free(bufferPtr);
198
libzip.free(errorPtr);
199
```
200

201
### Error Handling
202

203
Error codes and utilities for handling libzip errors.
204

205
```typescript { .api }
206
enum Errors {
207
  ZIP_ER_OK = 0,           // No error
208
  ZIP_ER_MULTIDISK = 1,    // Multi-disk zip archives not supported
209
  ZIP_ER_RENAME = 2,       // Renaming temporary file failed
210
  ZIP_ER_CLOSE = 3,        // Closing zip archive failed
211
  ZIP_ER_SEEK = 4,         // Seek error
212
  ZIP_ER_READ = 5,         // Read error
213
  ZIP_ER_WRITE = 6,        // Write error
214
  ZIP_ER_CRC = 7,          // CRC error
215
  ZIP_ER_ZIPCLOSED = 8,    // Containing zip archive was closed
216
  ZIP_ER_NOENT = 9,        // No such file
217
  ZIP_ER_EXISTS = 10,      // File already exists
218
  ZIP_ER_OPEN = 11,        // Can't open file
219
  ZIP_ER_TMPOPEN = 12,     // Failure to create temporary file
220
  ZIP_ER_ZLIB = 13,        // Zlib error
221
  ZIP_ER_MEMORY = 14,      // Memory allocation failure
222
  ZIP_ER_CHANGED = 15,     // Entry has been changed
223
  ZIP_ER_COMPNOTSUPP = 16, // Compression method not supported
224
  ZIP_ER_EOF = 17,         // Premature EOF
225
  ZIP_ER_INVAL = 18,       // Invalid argument
226
  ZIP_ER_NOZIP = 19,       // Not a zip archive
227
  ZIP_ER_INTERNAL = 20,    // Internal error
228
  ZIP_ER_INCONS = 21,      // Zip archive inconsistent
229
  ZIP_ER_REMOVE = 22,      // Can't remove file
230
  ZIP_ER_DELETED = 23,     // Entry has been deleted
231
  ZIP_ER_ENCRNOTSUPP = 24, // Encryption method not supported
232
  ZIP_ER_RDONLY = 25,      // Read-only archive
233
  ZIP_ER_NOPASSWD = 26,    // No password provided
234
  ZIP_ER_WRONGPASSWD = 27, // Wrong password provided
235
  ZIP_ER_OPNOTSUPP = 28,   // Operation not supported
236
  ZIP_ER_INUSE = 29,       // Resource still in use
237
  ZIP_ER_TELL = 30,        // Tell error
238
  ZIP_ER_COMPRESSED_DATA = 31 // Compressed data invalid
239
}
240
```
241

242
### WebAssembly Module Types
243

244
Low-level types for the Emscripten-compiled WebAssembly module.
245

246
```typescript { .api }
247
interface LibzipEmscriptenModule extends EmscriptenModule {
248
  cwrap: typeof cwrap;
249
  getValue: typeof getValue;
250
}
251
```
252

253
## Factory and Instance Management
254

255
Functions for managing libzip instance lifecycle and factory registration.
256

257
```typescript { .api }
258
/**
259
 * Set factory function for creating libzip instances
260
 * @param factory - Function that creates and returns a Libzip instance
261
 */
262
function setFactory(factory: () => Libzip): void;
263

264
/**
265
 * Get current libzip instance, creating one if needed
266
 * @returns The current Libzip instance
267
 */
268
function getInstance(): Libzip;
269

270
/**
271
 * Try to get existing instance without creating a new one
272
 * @returns The current Libzip instance or undefined if none exists
273
 */
274
function tryInstance(): Libzip | undefined;
275
```