0
# Utility Functions
1

2
Helper functions for memory mounting, archive creation, and path manipulation to support common ZIP operations and integration patterns. These utilities provide convenient abstractions for common ZIP-related tasks.
3

4
## Capabilities
5

6
### Memory Drive Mounting
7

8
Mount an in-memory ZIP filesystem that integrates with Node.js fs module, allowing transparent ZIP operations through standard filesystem calls.
9

10
```typescript { .api }
11
/**
12
 * Mount an in-memory ZIP filesystem at a specific mount point
13
 * Patches the provided fs object to handle ZIP operations transparently
14
 * @param origFs - Original fs module to patch
15
 * @param mountPoint - Filesystem path where ZIP should be mounted
16
 * @param source - ZIP archive buffer (defaults to empty archive)
17
 * @param opts - Configuration options
18
 * @returns ZipFS instance for the mounted archive
19
 */
20
function mountMemoryDrive(
21
  origFs: typeof fs, 
22
  mountPoint: PortablePath, 
23
  source?: Buffer | null, 
24
  opts?: MemoryDriveOpts
25
): ZipFS;
26

27
interface MemoryDriveOpts {
28
  /** Type checking flags for mount validation */
29
  typeCheck?: number | null;
30
}
31
```
32

33
**Usage Examples:**
34

35
```typescript
36
import { mountMemoryDrive } from "@yarnpkg/libzip";
37
import { ppath } from "@yarnpkg/fslib";
38
import fs from "fs";
39

40
// Mount empty ZIP at /virtual
41
const zipFs = mountMemoryDrive(
42
  fs,
43
  "/virtual" as ppath.PortablePath
44
);
45

46
// Now fs operations work transparently with the ZIP
47
fs.writeFileSync("/virtual/hello.txt", "Hello from memory ZIP!");
48
fs.mkdirSync("/virtual/docs");
49
fs.writeFileSync("/virtual/docs/readme.md", "# Documentation");
50

51
// Read back through fs
52
const content = fs.readFileSync("/virtual/hello.txt", "utf8");
53
const files = fs.readdirSync("/virtual");
54

55
// Mount existing ZIP archive
56
const existingZipBuffer = fs.readFileSync("existing.zip");
57
const existingZipFs = mountMemoryDrive(
58
  fs,
59
  "/mounted-archive" as ppath.PortablePath,
60
  existingZipBuffer,
61
  { typeCheck: 21 }
62
);
63

64
// Access files in the mounted archive
65
const archivedFiles = fs.readdirSync("/mounted-archive");
66
```
67

68
### Empty Archive Creation
69

70
Create an empty ZIP archive buffer that can be used as a starting point for new archives.
71

72
```typescript { .api }
73
/**
74
 * Create an empty ZIP archive buffer
75
 * Contains minimal ZIP structure with no entries
76
 * @returns Buffer containing empty ZIP archive data
77
 */
78
function makeEmptyArchive(): Buffer;
79
```
80

81
**Usage Examples:**
82

83
```typescript
84
import { makeEmptyArchive, ZipFS } from "@yarnpkg/libzip";
85

86
// Create empty archive buffer
87
const emptyZip = makeEmptyArchive();
88

89
// Use as starting point for new ZipFS
90
const zipFs = new ZipFS(emptyZip, {
91
  level: 6
92
});
93

94
// Add content to the initially empty archive
95
zipFs.writeFileSync("/first-file.txt" as ppath.PortablePath, "First content!");
96

97
// Save the archive
98
const finalArchive = zipFs.getBufferAndClose();
99
```
100

101
### Archive Path Detection
102

103
Extract archive portions from filesystem paths for ZIP file detection and mounting operations.
104

105
```typescript { .api }
106
/**
107
 * Extracts the archive part (ending in the first instance of extension) from a path
108
 * Used by ZipOpenFS to detect ZIP files within filesystem paths
109
 * @param path - The full filesystem path potentially containing an archive
110
 * @param extension - The archive file extension to look for (e.g., ".zip")
111
 * @returns The archive path portion or null if no archive detected
112
 */
113
function getArchivePart(path: string, extension: string): PortablePath | null;
114
```
115

116
**Usage Examples:**
117

118
```typescript
119
import { getArchivePart } from "@yarnpkg/libzip";
120

121
// Detect ZIP in path
122
const zipPath = getArchivePart(
123
  "/home/user/documents/project.zip/src/index.js", 
124
  ".zip"
125
);
126
// Returns: "/home/user/documents/project.zip"
127

128
const innerPath = "/home/user/documents/project.zip/src/index.js".slice(zipPath.length);
129
// innerPath: "/src/index.js"
130

131
// No archive in path
132
const regularPath = getArchivePart("/home/user/documents/regular.txt", ".zip");
133
// Returns: null
134

135
// Multiple extensions
136
const jarPath = getArchivePart("/apps/myapp.jar/META-INF/MANIFEST.MF", ".jar");
137
// Returns: "/apps/myapp.jar"
138

139
// Edge cases handled correctly
140
const noMatch = getArchivePart("/path/to/.zip", ".zip"); // Returns: null (disallows files named ".zip")
141
const multipleZips = getArchivePart("/path/first.zip/nested.zip/file.txt", ".zip");
142
// Returns: "/path/first.zip" (returns first match)
143
```
144

145
### File System Integration Utilities
146

147
Utilities for integrating ZIP operations with standard filesystem interfaces.
148

149
```typescript { .api }
150
/**
151
 * Unix timestamp conversion utility
152
 * Handles various time formats and converts to Unix timestamps for ZIP files
153
 * @param time - Time value as Date, string, or number
154
 * @returns Unix timestamp (seconds since epoch)
155
 */
156
function toUnixTimestamp(time: Date | string | number): number;
157
```
158

159
**Usage Example:**
160

161
```typescript
162
// Used internally but available for custom implementations
163
const now = toUnixTimestamp(new Date());
164
const fromString = toUnixTimestamp("1640995200"); // Unix timestamp string
165
const fromNumber = toUnixTimestamp(1640995200000); // Milliseconds since epoch
166
```
167

168
## Compression Utilities
169

170
Types and constants for managing ZIP compression settings.
171

172
```typescript { .api }
173
/** 
174
 * ZIP compression level specification
175
 * Numbers 0-9 represent standard compression levels
176
 * "mixed" allows different compression per file
177
 */
178
type ZipCompression = "mixed" | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
179

180
/**
181
 * Compression method and level tuple
182
 * First element: compression method (0=store, 8=deflate, etc.)
183
 * Second element: compression level (0-9)
184
 * null indicates no compression data
185
 */
186
type CompressionData = [compressionMethod: number, level: number] | null;
187

188
/** Default compression level for new archives */
189
const DEFAULT_COMPRESSION_LEVEL: ZipCompression = "mixed";
190
```
191

192
## Platform Constants
193

194
Operating system and ZIP format constants for cross-platform compatibility.
195

196
```typescript { .api }
197
/** Unix operating system constant for ZIP external attributes */
198
const ZIP_UNIX = 3;
199

200
/** Store compression method (no compression) */
201
const STORE = 0;
202

203
/** Deflate compression method (standard ZIP compression) */
204
const DEFLATE = 8;
205
```
206

207
**Usage Examples:**
208

209
```typescript
210
import { ZIP_UNIX, DEFLATE } from "@yarnpkg/libzip";
211

212
// Set Unix file permissions in ZIP
213
const fileAttributes = 0o644 << 16; // rw-r--r-- permissions
214
zipImpl.setExternalAttributes(fileIndex, ZIP_UNIX, fileAttributes);
215

216
// Use deflate compression
217
const compressionData: CompressionData = [DEFLATE, 6]; // Deflate level 6
218
zipImpl.setFileSource("file.txt" as ppath.PortablePath, compressionData, buffer);
219
```
220

221
## Configuration Types
222

223
```typescript { .api }
224
interface MemoryDriveOpts {
225
  /** 
226
   * Type checking configuration for mount validation
227
   * Used internally by MountFS for magic byte detection
228
   */
229
  typeCheck?: number | null;
230
}
231
```