0
# Virtual File System
1

2
Fast file system operations through a virtual interface that provides cached access to file metadata, dependencies, and content information. The HasteFS provides an efficient abstraction over the file system with built-in caching and fast lookup capabilities.
3

4
## Capabilities
5

6
### File Existence and Metadata
7

8
Core file system operations for checking file existence and retrieving metadata.
9

10
```typescript { .api }
11
/**
12
 * Check if a file exists in the virtual file system
13
 * @param path - Absolute path to the file
14
 * @returns True if file exists in the mapped file system
15
 */
16
exists(path: string): boolean;
17

18
/**
19
 * Get the size of a file in bytes
20
 * @param path - Absolute path to the file
21
 * @returns File size in bytes, or null if file doesn't exist
22
 */
23
getSize(path: string): number | null;
24

25
/**
26
 * Get the module name (Haste ID) for a file
27
 * @param file - Absolute path to the file
28
 * @returns Module name if file has one, null otherwise
29
 */
30
getModuleName(file: string): string | null;
31

32
/**
33
 * Get the SHA-1 hash of a file if computed during crawling
34
 * @param file - Absolute path to the file
35
 * @returns SHA-1 hash as hex string, or null if not computed or file doesn't exist
36
 */
37
getSha1(file: string): string | null;
38
```
39

40
### File Iteration and Listing
41

42
Methods for iterating over and listing files in the virtual file system.
43

44
```typescript { .api }
45
/**
46
 * Get all files tracked by the haste map as absolute paths
47
 * @returns Array of all absolute file paths
48
 */
49
getAllFiles(): Array<string>;
50

51
/**
52
 * Get iterator for absolute file paths, memory efficient for large projects
53
 * @returns Iterable yielding absolute file paths
54
 */
55
getAbsoluteFileIterator(): Iterable<string>;
56
```
57

58
### Dependency Analysis
59

60
Access to computed file dependencies for module resolution and build optimization.
61

62
```typescript { .api }
63
/**
64
 * Get the dependencies of a file as extracted during crawling
65
 * @param file - Absolute path to the file
66
 * @returns Array of dependency specifiers, null if file not found, empty array if no dependencies
67
 */
68
getDependencies(file: string): Array<string> | null;
69
```
70

71
### Pattern Matching and Search
72

73
Powerful file search capabilities using regular expressions and glob patterns.
74

75
```typescript { .api }
76
/**
77
 * Find files matching a regular expression or string pattern
78
 * @param pattern - RegExp or string pattern to match against absolute file paths
79
 * @returns Array of absolute paths to matching files
80
 */
81
matchFiles(pattern: RegExp | string): Array<string>;
82

83
/**
84
 * Find files matching glob patterns with optional root restriction
85
 * @param globs - Array of glob patterns to match
86
 * @param root - Optional root directory to make patterns relative to
87
 * @returns Set of absolute paths to matching files
88
 */
89
matchFilesWithGlob(
90
  globs: ReadonlyArray<string>,
91
  root: string | null
92
): Set<string>;
93
```
94

95
**Usage Examples:**
96

97
```typescript
98
import HasteMap from "jest-haste-map";
99

100
const hasteMap = await HasteMap.create({
101
  id: "my-project",
102
  extensions: ["js", "ts", "jsx", "tsx"],
103
  maxWorkers: 4,
104
  platforms: [],
105
  roots: ["/src"],
106
  retainAllFiles: true,
107
  rootDir: "/project/root",
108
});
109

110
const {hasteFS} = await hasteMap.build();
111

112
// Check file existence
113
if (hasteFS.exists("/project/root/src/components/Button.tsx")) {
114
  console.log("Button component exists");
115
}
116

117
// Get file metadata
118
const buttonSize = hasteFS.getSize("/project/root/src/components/Button.tsx");
119
console.log(`Button component is ${buttonSize} bytes`);
120

121
// Get all tracked files
122
const allFiles = hasteFS.getAllFiles();
123
console.log(`Tracking ${allFiles.length} files`);
124

125
// Memory-efficient iteration for large projects
126
for (const filePath of hasteFS.getAbsoluteFileIterator()) {
127
  if (filePath.endsWith('.test.js')) {
128
    console.log(`Found test file: ${filePath}`);
129
  }
130
}
131

132
// Get file dependencies
133
const dependencies = hasteFS.getDependencies("/project/root/src/App.tsx");
134
if (dependencies) {
135
  console.log("App.tsx depends on:", dependencies);
136
}
137

138
// Find files by pattern
139
const componentFiles = hasteFS.matchFiles(/\/components\/.*\.tsx$/);
140
console.log("Component files:", componentFiles);
141

142
// Find files by glob patterns
143
const testFiles = hasteFS.matchFilesWithGlob(
144
  ["**/*.test.js", "**/*.spec.js"],
145
  "/project/root"
146
);
147
console.log("Test files:", Array.from(testFiles));
148

149
// Find TypeScript files
150
const tsFiles = hasteFS.matchFiles("\\.ts$");
151
console.log("TypeScript files:", tsFiles);
152

153
// Get module names for Haste modules
154
const moduleName = hasteFS.getModuleName("/project/root/src/Button.js");
155
if (moduleName) {
156
  console.log(`File exports module: ${moduleName}`);
157
}
158

159
// Get SHA-1 hash if computed during crawling
160
const buttonSha1 = hasteFS.getSha1("/project/root/src/components/Button.tsx");
161
if (buttonSha1) {
162
  console.log(`Button component SHA-1: ${buttonSha1}`);
163
}
164
```
165

166
### HasteFS Implementation Details
167

168
The HasteFS class provides the concrete implementation of the IHasteFS interface.
169

170
```typescript { .api }
171
/**
172
 * Virtual file system implementation providing cached access to file metadata
173
 * and dependencies extracted during the haste map build process
174
 */
175
class HasteFS implements IHasteFS {
176
  /**
177
   * Create a HasteFS instance
178
   * @param options - Configuration with files map and root directory
179
   */
180
  constructor(options: {rootDir: string; files: FileData});
181
}
182
```
183

184
### File Data Structure
185

186
Internal representation of file metadata used by HasteFS.
187

188
```typescript { .api }
189
/**
190
 * Map of relative file paths to metadata arrays
191
 */
192
type FileData = Map<string, FileMetaData>;
193

194
/**
195
 * Efficient array-based file metadata storage
196
 * [id, mtime, size, visited, dependencies, sha1]
197
 */
198
type FileMetaData = [
199
  id: string,          // Module ID/name if applicable
200
  mtime: number,       // Last modified time in milliseconds
201
  size: number,        // File size in bytes
202
  visited: 0 | 1,      // Whether file has been processed (0 = false, 1 = true)
203
  dependencies: string, // Serialized dependencies joined by null character
204
  sha1: string | null | undefined, // SHA-1 hash if computed
205
];
206
```
207

208
### Integration with Module Resolution
209

210
HasteFS works closely with ModuleMap to provide complete project introspection.
211

212
```typescript
213
// Combined usage with module resolution
214
const {hasteFS, moduleMap} = await hasteMap.build();
215

216
// Find a module and get its dependencies
217
const buttonPath = moduleMap.getModule("Button");
218
if (buttonPath && hasteFS.exists(buttonPath)) {
219
  const buttonDeps = hasteFS.getDependencies(buttonPath);
220
  console.log("Button dependencies:", buttonDeps);
221
  
222
  const buttonSize = hasteFS.getSize(buttonPath);
223
  console.log(`Button is ${buttonSize} bytes`);
224
}
225

226
// Search for files and resolve them as modules
227
const utilFiles = hasteFS.matchFiles(/\/utils\/.*\.js$/);
228
for (const utilFile of utilFiles) {
229
  const moduleName = hasteFS.getModuleName(utilFile);
230
  if (moduleName) {
231
    console.log(`Utility ${moduleName} at ${utilFile}`);
232
  }
233
}
234
```