0
# File Map Core
1

2
Main FileMap class that orchestrates file system crawling, watching, and caching operations. This is the primary entry point for all metro-file-map functionality.
3

4
## Capabilities
5

6
### FileMap Class
7

8
The main class that extends EventEmitter to provide file system mapping capabilities.
9

10
```javascript { .api }
11
/**
12
 * Main FileMap class extending EventEmitter for file system operations
13
 */
14
class FileMap extends EventEmitter {
15
  /**
16
   * Factory method to create a new FileMap instance
17
   * @param options - Configuration options for the FileMap
18
   * @returns New FileMap instance
19
   */
20
  static create(options: InputOptions): FileMap;
21
  
22
  /**
23
   * Create a new FileMap instance
24
   * @param options - Configuration options for the FileMap
25
   */
26
  constructor(options: InputOptions);
27
  
28
  /**
29
   * Build the file map by crawling and processing files
30
   * @returns Promise resolving to build result with file system and maps
31
   */
32
  build(): Promise<BuildResult>;
33
  
34
  /**
35
   * Read cached data if available
36
   * @returns Promise resolving to cached data or null if not available
37
   */
38
  read(): Promise<CacheData | null>;
39
  
40
  /**
41
   * Clean up resources, stop watching, and close workers
42
   * @returns Promise that resolves when cleanup is complete
43
   */
44
  end(): Promise<void>;
45
}
46
```
47

48
**Usage Examples:**
49

50
```javascript
51
import FileMap from "metro-file-map";
52

53
// Create FileMap with basic configuration
54
const fileMap = new FileMap({
55
  extensions: ['.js', '.jsx', '.ts', '.tsx'],
56
  platforms: ['ios', 'android', 'native', 'web'],
57
  retainAllFiles: false,
58
  rootDir: process.cwd(),
59
  roots: ['./src', './lib'],
60
  maxWorkers: require('os').cpus().length,
61
  healthCheck: {
62
    enabled: false,
63
    interval: 30000,
64
    timeout: 5000,
65
    filePrefix: 'metro-file-map-health-check'
66
  }
67
});
68

69
// Alternative factory method
70
const fileMap2 = FileMap.create(options);
71
```
72

73
### Build Process
74

75
Orchestrates the complete file system analysis process.
76

77
```javascript { .api }
78
/**
79
 * Build result containing file system and module maps
80
 */
81
interface BuildResult {
82
  /** Virtual file system with querying capabilities */
83
  fileSystem: FileSystem;
84
  /** Haste module resolution map */
85
  hasteMap: HasteMap;
86
  /** Mock module map (null if mocks disabled) */
87
  mockMap: MockMap | null;
88
}
89
```
90

91
**Usage Examples:**
92

93
```javascript
94
// Perform complete file system build
95
const { fileSystem, hasteMap, mockMap } = await fileMap.build();
96

97
// Query results
98
const allFiles = fileSystem.getAllFiles();
99
console.log(`Found ${allFiles.length} files`);
100

101
// Find module by name
102
const componentPath = hasteMap.getModule('MyComponent', 'ios');
103
if (componentPath) {
104
  console.log(`MyComponent found at: ${componentPath}`);
105
}
106
```
107

108
### Event System
109

110
FileMap extends EventEmitter and emits various events during operation.
111

112
```javascript { .api }
113
/**
114
 * Events emitted by FileMap instance
115
 */
116
interface FileMapEvents {
117
  /** Emitted when files change during watch mode */
118
  'change': (event: ChangeEvent) => void;
119
  /** Emitted for watcher status updates */
120
  'status': (status: WatcherStatus) => void;
121
  /** Emitted for health check results (if enabled) */
122
  'healthCheck': (result: HealthCheckResult) => void;
123
  /** Emitted when metadata is updated */
124
  'metadata': () => void;
125
}
126
```
127

128
**Usage Examples:**
129

130
```javascript
131
// Listen for file changes in watch mode
132
fileMap.on('change', (changeEvent) => {
133
  console.log('Files changed:', changeEvent.eventsQueue.length);
134
  changeEvent.eventsQueue.forEach(event => {
135
    console.log(`${event.type}: ${event.filePath}`);
136
  });
137
});
138

139
// Listen for watcher status
140
fileMap.on('status', (status) => {
141
  if (status.type === 'watchman_slow_command') {
142
    console.log(`Slow ${status.command} command: ${status.timeElapsed}ms`);
143
  }
144
});
145

146
// Enable watch mode
147
const watchingFileMap = new FileMap({
148
  ...options,
149
  watch: true,
150
  useWatchman: true
151
});
152
```
153

154
### Static Properties
155

156
Static constants and utilities available on the FileMap class.
157

158
```javascript { .api }
159
/**
160
 * Constants for FileMetadata array indices
161
 */
162
static H: {
163
  ID: 0,
164
  MTIME: 1,
165
  SIZE: 2,
166
  VISITED: 3,
167
  DEPENDENCIES: 4,
168
  SHA1: 5,
169
  SYMLINK: 6,
170
  PATH: 0,
171
  TYPE: 1,
172
  MODULE: 0,
173
  PACKAGE: 1,
174
  GENERIC_PLATFORM: 'g',
175
  NATIVE_PLATFORM: 'native',
176
  DEPENDENCY_DELIM: '\0'
177
};
178
```
179

180
**Usage Examples:**
181

182
```javascript
183
// Access metadata constants
184
const H = FileMap.H;
185

186
// Use constants to read file metadata
187
function getModuleId(fileMetadata) {
188
  return fileMetadata[H.ID];
189
}
190

191
function getModifiedTime(fileMetadata) {
192
  return fileMetadata[H.MTIME];
193
}
194
```
195

196
### Cache Integration
197

198
FileMap integrates with cache managers for persistent storage.
199

200
```javascript { .api }
201
/**
202
 * Cache data structure
203
 */
204
interface CacheData {
205
  clocks: WatchmanClocks;
206
  fileSystemData: unknown;
207
  plugins: ReadonlyMap<string, unknown>;
208
}
209
```
210

211
**Usage Examples:**
212

213
```javascript
214
// Read existing cache
215
const cachedData = await fileMap.read();
216
if (cachedData) {
217
  console.log('Using cached data');
218
} else {
219
  console.log('No cache available, performing full crawl');
220
}
221

222
// Custom cache manager
223
import { DiskCacheManager } from "metro-file-map";
224

225
const customCacheManager = new DiskCacheManager({
226
  buildParameters: options,
227
  cacheDirectory: './custom-cache',
228
  cacheFilePrefix: 'my-app'
229
});
230

231
const fileMapWithCustomCache = new FileMap({
232
  ...options,
233
  cacheManagerFactory: () => customCacheManager
234
});
235
```
236

237
## Types
238

239
```javascript { .api }
240
type WatcherStatus = 
241
  | {
242
      type: 'watchman_slow_command';
243
      timeElapsed: number;
244
      command: 'watch-project' | 'query';
245
    }
246
  | {
247
      type: 'watchman_slow_command_complete';
248
      timeElapsed: number;
249
      command: 'watch-project' | 'query';
250
    }
251
  | {
252
      type: 'watchman_warning';
253
      warning: unknown;
254
      command: 'watch-project' | 'query';
255
    };
256

257
interface HealthCheckResult {
258
  isHealthy: boolean;
259
  reason?: string;
260
}
261

262
type WatchmanClocks = Map<string, WatchmanClockSpec>;
263

264
type WatchmanClockSpec = string | {
265
  scm: {
266
    'mergebase-with': string;
267
  };
268
};
269
```