0
# Metro File Map
1

2
Metro File Map is an experimental file system crawling, watching and mapping library designed specifically for the Metro bundler ecosystem. Originally forked from jest-haste-map, it provides comprehensive file system operations including directory traversal, file change monitoring, and mapping capabilities essential for JavaScript bundling workflows.
3

4
## Package Information
5

6
- **Package Name**: metro-file-map
7
- **Package Type**: npm
8
- **Language**: JavaScript (with Flow types)
9
- **Installation**: `npm install metro-file-map`
10

11
## Core Imports
12

13
```javascript
14
import FileMap, { DiskCacheManager, HastePlugin } from "metro-file-map";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const FileMap = require("metro-file-map").default;
21
const { DiskCacheManager, HastePlugin } = require("metro-file-map");
22
```
23

24
## Basic Usage
25

26
```javascript
27
import FileMap from "metro-file-map";
28

29
const fileMap = new FileMap({
30
  extensions: ['.js', '.json'],
31
  platforms: ['ios', 'android', 'native'],
32
  retainAllFiles: false,
33
  rootDir: '/path/to/project',
34
  roots: ['/path/to/project/src'],
35
  maxWorkers: 4,
36
  healthCheck: {
37
    enabled: false,
38
    interval: 30000,
39
    timeout: 5000,
40
    filePrefix: 'metro-file-map-health-check'
41
  }
42
});
43

44
// Build the file map
45
const result = await fileMap.build();
46
const { fileSystem, hasteMap } = result;
47

48
// Query the file system
49
const allFiles = fileSystem.getAllFiles();
50
const moduleName = hasteMap.getModule('MyComponent');
51

52
// Clean up
53
await fileMap.end();
54
```
55

56
## Architecture
57

58
Metro File Map is built around several key components:
59

60
- **FileMap Class**: Main orchestrator that coordinates crawling, watching, and caching operations
61
- **File System Interface**: Virtual file system abstraction (TreeFS) with querying capabilities
62
- **Watcher System**: Cross-platform file watching with Watchman and fallback support
63
- **Plugin Architecture**: Extensible system for Haste modules, mocks, and custom functionality
64
- **Cache Management**: Pluggable caching system with disk-based default implementation
65
- **Worker Processing**: Multi-threaded file processing using jest-worker for performance
66

67
## Capabilities
68

69
### File Map Core
70

71
Main FileMap class for orchestrating file system operations, watching, and caching.
72

73
```javascript { .api }
74
class FileMap extends EventEmitter {
75
  static create(options: InputOptions): FileMap;
76
  constructor(options: InputOptions);
77
  build(): Promise<BuildResult>;
78
  read(): Promise<CacheData | null>;
79
  end(): Promise<void>;
80
}
81

82
interface BuildResult {
83
  fileSystem: FileSystem,
84
  hasteMap: HasteMap,
85
  mockMap: MockMap | null
86
}
87
```
88

89
[File Map Core](./file-map-core.md)
90

91
### File System Interface
92

93
Virtual file system providing querying, lookup, and metadata operations.
94

95
```javascript { .api }
96
interface FileSystem {
97
  exists(file: string): boolean;
98
  getAllFiles(): Array<string>;
99
  getDependencies(file: string): Array<string> | null;
100
  getModuleName(file: string): string | null;
101
  getSha1(file: string): string | null;
102
  matchFiles(opts: MatchFilesOptions): Iterable<string>;
103
  lookup(mixedPath: string): LookupResult;
104
}
105
```
106

107
[File System Interface](./file-system.md)
108

109
### Haste Module System
110

111
Haste module resolution and conflict detection system.
112

113
```javascript { .api }
114
interface HasteMap {
115
  getModule(name: string, platform?: string, supportsNativePlatform?: boolean, type?: number): string | null;
116
  getPackage(name: string, platform?: string, supportsNativePlatform?: boolean): string | null;
117
  computeConflicts(): Array<HasteConflict>;
118
}
119
```
120

121
[Haste Module System](./haste-system.md)
122

123
### Cache Management
124

125
Pluggable caching system with disk-based implementation for persistent storage.
126

127
```javascript { .api }
128
interface CacheManager {
129
  read(): Promise<CacheData | null>;
130
  write(getSnapshot: () => CacheData, opts: CacheManagerWriteOptions): Promise<void>;
131
  end(): Promise<void>;
132
}
133

134
class DiskCacheManager implements CacheManager {
135
  constructor(options: CacheManagerFactoryOptions, config: DiskCacheConfig);
136
  static getCacheFilePath(buildParameters: BuildParameters, cacheFilePrefix?: string, cacheDirectory?: string): string;
137
}
138
```
139

140
[Cache Management](./cache-management.md)
141

142
### Plugin System
143

144
Extensible plugin system for Haste modules, mocks, and custom file processing.
145

146
```javascript { .api }
147
interface FileMapPlugin<SerializableState> {
148
  +name: string;
149
  initialize(initOptions: FileMapPluginInitOptions<SerializableState>): Promise<void>;
150
  assertValid(): void;
151
  bulkUpdate(delta: FileMapDelta): Promise<void>;
152
  getSerializableSnapshot(): SerializableState;
153
  onRemovedFile(relativeFilePath: string, fileMetadata: FileMetadata): void;
154
  onNewOrModifiedFile(relativeFilePath: string, fileMetadata: FileMetadata): void;
155
  getCacheKey(): string;
156
}
157
```
158

159
[Plugin System](./plugin-system.md)
160

161
### Error Handling
162

163
Specialized error classes for Haste conflicts and duplicate candidates.
164

165
```javascript { .api }
166
class HasteConflictsError extends Error {
167
  constructor(conflicts: Array<HasteConflict>);
168
  getDetailedMessage(pathsRelativeToRoot?: string): string;
169
}
170

171
class DuplicateHasteCandidatesError extends Error {
172
  constructor(name: string, platform: string, supportsNativePlatform: boolean, duplicatesSet: DuplicatesSet);
173
}
174
```
175

176
[Error Handling](./error-handling.md)
177

178
## Types
179

180
```javascript { .api }
181
interface InputOptions {
182
  // Required
183
  extensions: ReadonlyArray<string>;
184
  platforms: ReadonlyArray<string>;
185
  retainAllFiles: boolean;
186
  rootDir: string;
187
  roots: ReadonlyArray<string>;
188
  maxWorkers: number;
189
  healthCheck: HealthCheckOptions;
190
  
191
  // Optional
192
  computeDependencies?: boolean;
193
  computeSha1?: boolean;
194
  enableSymlinks?: boolean;
195
  forceNodeFilesystemAPI?: boolean;
196
  ignorePattern?: RegExp;
197
  mocksPattern?: string;
198
  skipPackageJson?: boolean;
199
  dependencyExtractor?: string;
200
  hasteImplModulePath?: string;
201
  perfLoggerFactory?: PerfLoggerFactory;
202
  resetCache?: boolean;
203
  throwOnModuleCollision?: boolean;
204
  useWatchman?: boolean;
205
  watch?: boolean;
206
  watchmanDeferStates?: ReadonlyArray<string>;
207
  console?: Console;
208
  cacheManagerFactory?: CacheManagerFactory;
209
  enableHastePackages?: boolean;
210
  enableWorkerThreads?: boolean;
211
  maxFilesPerWorker?: number;
212
}
213

214
interface HealthCheckOptions {
215
  enabled: boolean;
216
  interval: number;
217
  timeout: number;
218
  filePrefix: string;
219
}
220

221
interface ChangeEvent {
222
  logger: RootPerfLogger | null;
223
  eventsQueue: EventsQueue;
224
}
225

226
interface ChangeEventMetadata {
227
  modifiedTime: number | null;
228
  size: number | null;
229
  type: 'f' | 'd' | 'l'; // File, Directory, Link
230
}
231

232
type FileMetadata = [
233
  string,    // id
234
  number,    // mtime
235
  number,    // size  
236
  0 | 1,     // visited
237
  string,    // dependencies
238
  string,    // sha1
239
  0 | 1 | string // symlink (0=no, 1=yes, string=target)
240
];
241

242
interface HasteConflict {
243
  id: string;
244
  platform: string | null;
245
  absolutePaths: Array<string>;
246
  type: 'duplicate' | 'shadowing';
247
}
248
```