0
# Filesystem Operations
1

2
High-level filesystem interface for ZIP archives supporting standard file operations like read, write, mkdir, and stat. These classes provide familiar filesystem semantics while working with ZIP archives, integrating seamlessly with the Yarn package manager ecosystem.
3

4
## Capabilities
5

6
### ZipFS Class
7

8
Main filesystem implementation for ZIP archives, extending the base filesystem interface with ZIP-specific functionality.
9

10
```typescript { .api }
11
/**
12
 * Filesystem implementation for ZIP archives
13
 * Provides standard filesystem operations on ZIP files
14
 */
15
class ZipFS extends BasePortableFakeFS {
16
  constructor(source: PortablePath | Buffer, options?: ZipBufferOptions | ZipPathOptions);
17
  
18
  // File operations
19
  readFileSync(p: PortablePath, encoding?: BufferEncoding): string | Buffer;
20
  writeFileSync(p: PortablePath, data: string | Buffer, options?: WriteFileOptions): void;
21
  appendFileSync(p: PortablePath, data: string | Buffer): void;
22
  
23
  // Directory operations
24
  mkdirSync(p: PortablePath, options?: MkdirOptions): void;
25
  rmdirSync(p: PortablePath, options?: RmdirOptions): void;
26
  readdirSync(p: PortablePath, options?: ReaddirOptions): string[] | Dirent[];
27
  
28
  // Metadata operations
29
  statSync(p: PortablePath, options?: StatSyncOptions): Stats;
30
  lstatSync(p: PortablePath, options?: StatSyncOptions): Stats;
31
  
32
  // File system operations
33
  existsSync(p: PortablePath): boolean;
34
  unlinkSync(p: PortablePath): void;
35
  renameSync(oldP: PortablePath, newP: PortablePath): void;
36
  copyFileSync(src: PortablePath, dest: PortablePath): void;
37
  
38
  // Stream operations
39
  createReadStream(p: PortablePath, options?: CreateReadStreamOptions): ReadStream;
40
  createWriteStream(p: PortablePath, options?: CreateWriteStreamOptions): WriteStream;
41
  
42
  // Advanced operations
43
  openSync(p: PortablePath, flags: string | number, mode?: number): number;
44
  closeSync(fd: number): void;
45
  readSync(fd: number, buffer: Buffer, offset: number, length: number, position: number): number;
46
  writeSync(fd: number, buffer: Buffer, offset?: number, length?: number, position?: number): number;
47
}
48
```
49

50
**Usage Examples:**
51

52
```typescript
53
import { ZipFS } from "@yarnpkg/libzip";
54
import { ppath } from "@yarnpkg/fslib";
55

56
// Create new archive
57
const zipFs = new ZipFS("/path/to/new-archive.zip" as ppath.PortablePath, {
58
  create: true,
59
  level: 6 // compression level
60
});
61

62
// Write files and directories
63
zipFs.mkdirSync("/src" as ppath.PortablePath);
64
zipFs.writeFileSync("/src/index.js" as ppath.PortablePath, `
65
  console.log("Hello from ZIP!");
66
`);
67

68
// Read archive contents
69
const files = zipFs.readdirSync("/" as ppath.PortablePath);
70
const content = zipFs.readFileSync("/src/index.js" as ppath.PortablePath, "utf8");
71

72
// Work with existing archive
73
const existingZip = new ZipFS("/existing.zip" as ppath.PortablePath, {
74
  readOnly: true
75
});
76

77
// Check file existence and get stats
78
if (existingZip.existsSync("/readme.txt" as ppath.PortablePath)) {
79
  const stats = existingZip.statSync("/readme.txt" as ppath.PortablePath);
80
  console.log(`File size: ${stats.size} bytes`);
81
}
82
```
83

84
### ZipOpenFS Class
85

86
Automatic ZIP file mounting filesystem that transparently handles ZIP files within filesystem paths, providing seamless access to ZIP contents.
87

88
```typescript { .api }
89
/**
90
 * Automatic ZIP file mounting filesystem
91
 * Transparently handles ZIP files in filesystem paths
92
 */
93
class ZipOpenFS extends MountFS<ZipFS> {
94
  constructor(opts?: ZipOpenFSOptions);
95
  
96
  // All standard filesystem methods inherited from MountFS
97
  // Automatically detects and mounts ZIP files based on file extensions
98
  
99
  saveAndClose(): void;
100
}
101

102
/**
103
 * Execute a function with a ZipOpenFS instance, automatically cleaning up afterward
104
 */
105
static openPromise<T>(
106
  fn: (zipOpenFs: ZipOpenFS) => Promise<T>, 
107
  opts?: ZipOpenFSOptions
108
): Promise<T>;
109
```
110

111
**Usage Examples:**
112

113
```typescript
114
import { ZipOpenFS } from "@yarnpkg/libzip";
115
import { ppath } from "@yarnpkg/fslib";
116

117
// Automatic mounting approach
118
const zipOpenFs = new ZipOpenFS({
119
  readOnlyArchives: true,
120
  fileExtensions: [".zip", ".jar"] // Support multiple archive types
121
});
122

123
// Access files inside ZIP transparently
124
const content = zipOpenFs.readFileSync(
125
  "/path/to/archive.zip/internal/file.txt" as ppath.PortablePath, 
126
  "utf8"
127
);
128

129
// List contents of ZIP
130
const zipContents = zipOpenFs.readdirSync(
131
  "/path/to/archive.zip" as ppath.PortablePath
132
);
133

134
// Temporary scope pattern
135
await ZipOpenFS.openPromise(async (zipOpenFs) => {
136
  const stats = zipOpenFs.statSync("/archive.zip/config.json" as ppath.PortablePath);
137
  const config = JSON.parse(
138
    zipOpenFs.readFileSync("/archive.zip/config.json" as ppath.PortablePath, "utf8")
139
  );
140
  
141
  return processConfig(config);
142
}, {
143
  readOnlyArchives: true
144
});
145
```
146

147
### Archive Path Utility
148

149
Extract archive portions from filesystem paths for ZIP file detection and mounting.
150

151
```typescript { .api }
152
/**
153
 * Extracts the archive part (ending in the first instance of extension) from a path
154
 * @param path - The full filesystem path
155
 * @param extension - The archive file extension (e.g., ".zip")
156
 * @returns The archive path portion or null if not found
157
 */
158
function getArchivePart(path: string, extension: string): PortablePath | null;
159
```
160

161
**Usage Example:**
162

163
```typescript
164
import { getArchivePart } from "@yarnpkg/libzip";
165

166
const archivePath = getArchivePart("/home/user/docs/archive.zip/folder/file.txt", ".zip");
167
// Returns: "/home/user/docs/archive.zip"
168

169
const noArchive = getArchivePart("/home/user/docs/regular/file.txt", ".zip");
170
// Returns: null
171
```
172

173
## Configuration Types
174

175
```typescript { .api }
176
interface ZipBufferOptions {
177
  /** Custom ZIP implementation class to use instead of default */
178
  customZipImplementation?: ZipImplementationClass;
179
  /** Whether the archive should be opened in read-only mode */
180
  readOnly?: boolean;
181
  /** Pre-computed file stats to avoid filesystem calls */
182
  stats?: Stats;
183
  /** Compression level for new files (0-9 or "mixed") */
184
  level?: ZipCompression;
185
}
186

187
interface ZipPathOptions extends ZipBufferOptions {
188
  /** Base filesystem to use for reading the ZIP file */
189
  baseFs?: FakeFS<PortablePath>;
190
  /** Whether to create the ZIP file if it doesn't exist */
191
  create?: boolean;
192
}
193

194
interface ZipOpenFSOptions {
195
  /** Libzip instance or factory function */
196
  libzip?: Libzip | (() => Libzip);
197
  /** Whether mounted archives should be opened read-only */
198
  readOnlyArchives?: boolean;
199
  /** Custom ZIP implementation for mounted archives */
200
  customZipImplementation?: ZipImplementationClass;
201
  /** File extensions to treat as ZIP archives (defaults to [".zip"]) */
202
  fileExtensions?: Array<string> | null;
203
}
204
```
205

206
## Constants
207

208
```typescript { .api }
209
/** Unix operating system constant for ZIP file attributes */
210
const ZIP_UNIX = 3;
211

212
/** Store compression method (no compression) */
213
const STORE = 0;
214

215
/** Deflate compression method (standard ZIP compression) */
216
const DEFLATE = 8;
217

218
/** Default compression level setting */
219
const DEFAULT_COMPRESSION_LEVEL: ZipCompression = "mixed";
220
```