0
# jest-haste-map
1

2
jest-haste-map is a high-performance file system mapping and watching library designed for efficient project file discovery and change tracking. It serves as a core component of the Jest testing framework, providing fast file lookups, parallel crawling capabilities, and cached file system operations that significantly improve performance in large JavaScript/TypeScript projects.
3

4
## Package Information
5

6
- **Package Name**: jest-haste-map
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install jest-haste-map`
10

11
## Core Imports
12

13
```typescript
14
import HasteMap, { ModuleMap } from "jest-haste-map";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const HasteMap = require("jest-haste-map").default;
21
const { ModuleMap } = require("jest-haste-map");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import HasteMap from "jest-haste-map";
28
import os from "os";
29

30
// Create a haste map for your project
31
const hasteMap = await HasteMap.create({
32
  id: "myproject",
33
  extensions: ["js", "ts", "jsx", "tsx"],
34
  maxWorkers: os.availableParallelism(),
35
  platforms: [], // For React Native support
36
  roots: ["/path/to/project"],
37
  retainAllFiles: true,
38
  rootDir: "/path/to/project",
39
});
40

41
// Build the file system map
42
const { hasteFS, moduleMap } = await hasteMap.build();
43

44
// Use the virtual file system
45
const allFiles = hasteFS.getAllFiles();
46
const dependencies = hasteFS.getDependencies("/path/to/file.js");
47

48
// Resolve modules
49
const modulePath = moduleMap.getModule("MyComponent");
50
```
51

52
## Architecture
53

54
jest-haste-map is built around several key components:
55

56
- **HasteMap**: Main orchestrator that manages file system crawling, caching, and watching
57
- **HasteFS**: Virtual file system interface providing fast file operations and metadata access
58
- **ModuleMap**: Module resolution system supporting platform-specific files and package.json resolution
59
- **Parallel Crawling**: Worker processes for concurrent file analysis and dependency extraction
60
- **Caching System**: In-memory and disk-based caches for optimal performance
61
- **File Watching**: Real-time file system monitoring using Watchman, FSEvents, or Node.js fs.watch
62

63
## Capabilities
64

65
### File System Mapping
66

67
Core file system crawling and mapping functionality for creating fast lookups of project files. Supports parallel processing and intelligent caching.
68

69
```typescript { .api }
70
class HasteMap extends EventEmitter implements IHasteMap {
71
  static create(options: Options): Promise<IHasteMap>;
72
  build(): Promise<{hasteFS: IHasteFS; moduleMap: IModuleMap}>;
73
  end(): Promise<void>;
74
}
75

76
interface Options {
77
  id: string;
78
  extensions: Array<string>;
79
  maxWorkers: number;
80
  platforms: Array<string>;
81
  retainAllFiles: boolean;
82
  rootDir: string;
83
  roots: Array<string>;
84
  cacheDirectory?: string;
85
  computeDependencies?: boolean;
86
  computeSha1?: boolean;
87
  console?: Console;
88
  dependencyExtractor?: string | null;
89
  enableSymlinks?: boolean;
90
  forceNodeFilesystemAPI?: boolean;
91
  hasteImplModulePath?: string;
92
  hasteMapModulePath?: string;
93
  ignorePattern?: HasteRegExp;
94
  mocksPattern?: string;
95
  resetCache?: boolean;
96
  skipPackageJson?: boolean;
97
  throwOnModuleCollision?: boolean;
98
  useWatchman?: boolean;
99
  watch?: boolean;
100
  workerThreads?: boolean;
101
}
102
```
103

104
[File System Mapping](./file-system-mapping.md)
105

106
### Virtual File System
107

108
Fast file system operations through a virtual interface that provides cached access to file metadata, dependencies, and content information.
109

110
```typescript { .api }
111
interface IHasteFS {
112
  exists(path: string): boolean;
113
  getAllFiles(): Array<string>;
114
  getAbsoluteFileIterator(): Iterable<string>;
115
  getDependencies(file: string): Array<string> | null;
116
  getSize(path: string): number | null;
117
  getSha1(file: string): string | null;
118
  matchFiles(pattern: RegExp | string): Array<string>;
119
  matchFilesWithGlob(globs: ReadonlyArray<string>, root: string | null): Set<string>;
120
  getModuleName(file: string): string | null;
121
}
122
```
123

124
[Virtual File System](./virtual-file-system.md)
125

126
### Module Resolution
127

128
Module resolution system that maps module names to file paths with support for platform-specific extensions, package.json resolution, and mock files.
129

130
```typescript { .api }
131
interface IModuleMap {
132
  getModule(
133
    name: string,
134
    platform?: string | null,
135
    supportsNativePlatform?: boolean | null,
136
    type?: HTypeValue | null
137
  ): string | null;
138
  getPackage(
139
    name: string,
140
    platform: string | null | undefined,
141
    _supportsNativePlatform: boolean | null
142
  ): string | null;
143
  getMockModule(name: string): string | undefined;
144
  getRawModuleMap(): RawModuleMap;
145
  toJSON(): SerializableModuleMap;
146
}
147

148
const ModuleMap = {
149
  create: (rootPath: string) => IModuleMap;
150
};
151
```
152

153
[Module Resolution](./module-resolution.md)
154

155
### File System Watching
156

157
Real-time file system monitoring for interactive development tools, providing change events and automatic map updates.
158

159
```typescript { .api }
160
interface IHasteMap {
161
  on(eventType: 'change', handler: (event: ChangeEvent) => void): void;
162
}
163

164
interface ChangeEvent {
165
  eventsQueue: EventsQueue;
166
  hasteFS: IHasteFS;
167
  moduleMap: IModuleMap;
168
}
169
```
170

171
[File System Watching](./file-system-watching.md)
172

173
## Core Types
174

175
```typescript { .api }
176
type HasteRegExp = RegExp | ((str: string) => boolean);
177

178
interface HasteMapStatic {
179
  getCacheFilePath(tmpdir: string, name: string, ...extra: Array<string>): string;
180
  getModuleMapFromJSON(json: SerializableModuleMap): IModuleMap;
181
}
182

183
interface EventsQueue extends Array<{
184
  filePath: string;
185
  stat: Stats | undefined;
186
  type: string;
187
}> {}
188

189
interface SerializableModuleMap {
190
  duplicates: ReadonlyArray<[string, [string, [string, [string, number]]]]>;
191
  map: ReadonlyArray<[string, ModuleMapItem]>;
192
  mocks: ReadonlyArray<[string, string]>;
193
  rootDir: string;
194
}
195

196
type ModuleMapItem = {[platform: string]: ModuleMetaData};
197
type ModuleMetaData = [path: string, type: number];
198

199
type DuplicatesSet = Map<string, number>;
200
type DuplicatesIndex = Map<string, Map<string, DuplicatesSet>>;
201

202
class DuplicateHasteCandidatesError extends Error {
203
  hasteName: string;
204
  platform: string | null;
205
  supportsNativePlatform: boolean;
206
  duplicatesSet: DuplicatesSet;
207
  constructor(
208
    name: string,
209
    platform: string,
210
    supportsNativePlatform: boolean,
211
    duplicatesSet: DuplicatesSet
212
  );
213
}
214
```