1 | /**
|
2 | * Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved.
|
3 | *
|
4 | * This source code is licensed under the MIT license found in the
|
5 | * LICENSE file in the root directory of this source tree.
|
6 | */
|
7 | /// <reference types="node" />
|
8 | import { EventEmitter } from 'events';
|
9 | import type { Config } from '@jest/types';
|
10 | import H from './constants';
|
11 | import HasteFS from './HasteFS';
|
12 | import HasteModuleMap, { SerializableModuleMap as HasteSerializableModuleMap } from './ModuleMap';
|
13 | import type { ChangeEvent, HasteRegExp, InternalHasteMap, HasteMap as InternalHasteMapObject } from './types';
|
14 | declare type HType = typeof H;
|
15 | declare type Options = {
|
16 | cacheDirectory?: string;
|
17 | computeDependencies?: boolean;
|
18 | computeSha1?: boolean;
|
19 | console?: Console;
|
20 | dependencyExtractor?: string | null;
|
21 | extensions: Array<string>;
|
22 | forceNodeFilesystemAPI?: boolean;
|
23 | hasteImplModulePath?: string;
|
24 | ignorePattern?: HasteRegExp;
|
25 | maxWorkers: number;
|
26 | mocksPattern?: string;
|
27 | name: string;
|
28 | platforms: Array<string>;
|
29 | resetCache?: boolean;
|
30 | retainAllFiles: boolean;
|
31 | rootDir: string;
|
32 | roots: Array<string>;
|
33 | skipPackageJson?: boolean;
|
34 | throwOnModuleCollision?: boolean;
|
35 | useWatchman?: boolean;
|
36 | watch?: boolean;
|
37 | };
|
38 | declare namespace HasteMap {
|
39 | type ModuleMap = HasteModuleMap;
|
40 | type SerializableModuleMap = HasteSerializableModuleMap;
|
41 | type FS = HasteFS;
|
42 | type HasteMapObject = InternalHasteMapObject;
|
43 | type HasteChangeEvent = ChangeEvent;
|
44 | }
|
45 | /**
|
46 | * HasteMap is a JavaScript implementation of Facebook's haste module system.
|
47 | *
|
48 | * This implementation is inspired by https://github.com/facebook/node-haste
|
49 | * and was built with for high-performance in large code repositories with
|
50 | * hundreds of thousands of files. This implementation is scalable and provides
|
51 | * predictable performance.
|
52 | *
|
53 | * Because the haste map creation and synchronization is critical to startup
|
54 | * performance and most tasks are blocked by I/O this class makes heavy use of
|
55 | * synchronous operations. It uses worker processes for parallelizing file
|
56 | * access and metadata extraction.
|
57 | *
|
58 | * The data structures created by `jest-haste-map` can be used directly from the
|
59 | * cache without further processing. The metadata objects in the `files` and
|
60 | * `map` objects contain cross-references: a metadata object from one can look
|
61 | * up the corresponding metadata object in the other map. Note that in most
|
62 | * projects, the number of files will be greater than the number of haste
|
63 | * modules one module can refer to many files based on platform extensions.
|
64 | *
|
65 | * type HasteMap = {
|
66 | * clocks: WatchmanClocks,
|
67 | * files: {[filepath: string]: FileMetaData},
|
68 | * map: {[id: string]: ModuleMapItem},
|
69 | * mocks: {[id: string]: string},
|
70 | * }
|
71 | *
|
72 | * // Watchman clocks are used for query synchronization and file system deltas.
|
73 | * type WatchmanClocks = {[filepath: string]: string};
|
74 | *
|
75 | * type FileMetaData = {
|
76 | * id: ?string, // used to look up module metadata objects in `map`.
|
77 | * mtime: number, // check for outdated files.
|
78 | * size: number, // size of the file in bytes.
|
79 | * visited: boolean, // whether the file has been parsed or not.
|
80 | * dependencies: Array<string>, // all relative dependencies of this file.
|
81 | * sha1: ?string, // SHA-1 of the file, if requested via options.
|
82 | * };
|
83 | *
|
84 | * // Modules can be targeted to a specific platform based on the file name.
|
85 | * // Example: platform.ios.js and Platform.android.js will both map to the same
|
86 | * // `Platform` module. The platform should be specified during resolution.
|
87 | * type ModuleMapItem = {[platform: string]: ModuleMetaData};
|
88 | *
|
89 | * //
|
90 | * type ModuleMetaData = {
|
91 | * path: string, // the path to look up the file object in `files`.
|
92 | * type: string, // the module type (either `package` or `module`).
|
93 | * };
|
94 | *
|
95 | * Note that the data structures described above are conceptual only. The actual
|
96 | * implementation uses arrays and constant keys for metadata storage. Instead of
|
97 | * `{id: 'flatMap', mtime: 3421, size: 42, visited: true, dependencies: []}` the real
|
98 | * representation is similar to `['flatMap', 3421, 42, 1, []]` to save storage space
|
99 | * and reduce parse and write time of a big JSON blob.
|
100 | *
|
101 | * The HasteMap is created as follows:
|
102 | * 1. read data from the cache or create an empty structure.
|
103 | *
|
104 | * 2. crawl the file system.
|
105 | * * empty cache: crawl the entire file system.
|
106 | * * cache available:
|
107 | * * if watchman is available: get file system delta changes.
|
108 | * * if watchman is unavailable: crawl the entire file system.
|
109 | * * build metadata objects for every file. This builds the `files` part of
|
110 | * the `HasteMap`.
|
111 | *
|
112 | * 3. parse and extract metadata from changed files.
|
113 | * * this is done in parallel over worker processes to improve performance.
|
114 | * * the worst case is to parse all files.
|
115 | * * the best case is no file system access and retrieving all data from
|
116 | * the cache.
|
117 | * * the average case is a small number of changed files.
|
118 | *
|
119 | * 4. serialize the new `HasteMap` in a cache file.
|
120 | * Worker processes can directly access the cache through `HasteMap.read()`.
|
121 | *
|
122 | */
|
123 | declare class HasteMap extends EventEmitter {
|
124 | private _buildPromise;
|
125 | private _cachePath;
|
126 | private _changeInterval?;
|
127 | private _console;
|
128 | private _options;
|
129 | private _watchers;
|
130 | private _worker;
|
131 | constructor(options: Options);
|
132 | static getCacheFilePath(tmpdir: Config.Path, name: string, ...extra: Array<string>): string;
|
133 | getCacheFilePath(): string;
|
134 | build(): Promise<InternalHasteMapObject>;
|
135 | /**
|
136 | * 1. read data from the cache or create an empty structure.
|
137 | */
|
138 | read(): InternalHasteMap;
|
139 | readModuleMap(): HasteModuleMap;
|
140 | /**
|
141 | * 2. crawl the file system.
|
142 | */
|
143 | private _buildFileMap;
|
144 | /**
|
145 | * 3. parse and extract metadata from changed files.
|
146 | */
|
147 | private _processFile;
|
148 | private _buildHasteMap;
|
149 | private _cleanup;
|
150 | /**
|
151 | * 4. serialize the new `HasteMap` in a cache file.
|
152 | */
|
153 | private _persist;
|
154 | /**
|
155 | * Creates workers or parses files and extracts metadata in-process.
|
156 | */
|
157 | private _getWorker;
|
158 | private _crawl;
|
159 | /**
|
160 | * Watch mode
|
161 | */
|
162 | private _watch;
|
163 | /**
|
164 | * This function should be called when the file under `filePath` is removed
|
165 | * or changed. When that happens, we want to figure out if that file was
|
166 | * part of a group of files that had the same ID. If it was, we want to
|
167 | * remove it from the group. Furthermore, if there is only one file
|
168 | * remaining in the group, then we want to restore that single file as the
|
169 | * correct resolution for its ID, and cleanup the duplicates index.
|
170 | */
|
171 | private _recoverDuplicates;
|
172 | end(): Promise<void>;
|
173 | /**
|
174 | * Helpers
|
175 | */
|
176 | private _ignore;
|
177 | private _createEmptyMap;
|
178 | static H: HType;
|
179 | static DuplicateError: typeof DuplicateError;
|
180 | static ModuleMap: typeof HasteModuleMap;
|
181 | }
|
182 | declare class DuplicateError extends Error {
|
183 | mockPath1: string;
|
184 | mockPath2: string;
|
185 | constructor(mockPath1: string, mockPath2: string);
|
186 | }
|
187 | export = HasteMap;
|