0
# Jest Resolve Dependencies
1

2
Jest Resolve Dependencies provides dependency resolution utilities specifically designed for the Jest testing framework. It exports a DependencyResolver class that handles module dependency analysis, including resolving direct dependencies of modules and retrieving transitive inverse dependencies for intelligent test re-execution.
3

4
## Package Information
5

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

11
### Peer Dependencies
12

13
This package requires additional Jest packages for full functionality:
14

15
```bash
16
npm install jest-haste-map jest-resolve jest-snapshot
17
```
18

19
**Note**: This package is primarily designed for internal use by Jest. Most applications won't need to use it directly as Jest handles dependency resolution automatically.
20

21
## Core Imports
22

23
```typescript
24
import { DependencyResolver, type ResolvedModule } from "jest-resolve-dependencies";
25
import type { IHasteFS } from "jest-haste-map";
26
import type Resolver, { ResolveModuleConfig } from "jest-resolve";
27
import { buildSnapshotResolver, type SnapshotResolver } from "jest-snapshot";
28
```
29

30
For CommonJS:
31

32
```javascript
33
const { DependencyResolver } = require("jest-resolve-dependencies");
34
const { buildSnapshotResolver } = require("jest-snapshot");
35
```
36

37
## Basic Usage
38

39
**Important**: This package is primarily used internally by Jest. The examples below show how to use it directly, but most developers will interact with it through Jest's testing framework rather than directly.
40

41
```typescript
42
import { DependencyResolver } from "jest-resolve-dependencies";
43
import type { IHasteFS } from "jest-haste-map";
44
import type Resolver from "jest-resolve";
45
import { buildSnapshotResolver } from "jest-snapshot";
46

47
// Create resolver instance (typically created by Jest runtime, not manually)
48
const dependencyResolver = new DependencyResolver(
49
  resolver,        // Resolver instance from jest-resolve
50
  hasteFS,         // IHasteFS instance from jest-haste-map  
51
  snapshotResolver // SnapshotResolver instance from jest-snapshot
52
);
53

54
// Resolve direct dependencies of a file
55
const dependencies = dependencyResolver.resolve("/path/to/module.js");
56
console.log(dependencies); // Array of resolved dependency paths
57

58
// Find files that depend on changed files (for watch mode)
59
const changedFiles = new Set(["/path/to/changed-file.js"]);
60
const affectedTests = dependencyResolver.resolveInverse(
61
  changedFiles,
62
  (file) => file.endsWith('.test.js') // Filter for test files
63
);
64
console.log(affectedTests); // Array of test files that need to re-run
65
```
66

67
## Architecture
68

69
Jest Resolve Dependencies is built around key dependency resolution concepts:
70

71
- **Direct Resolution**: Finding immediate dependencies of a module using Jest's Haste file system
72
- **Mock Resolution**: Handling Jest mock modules alongside regular dependencies
73
- **Inverse Resolution**: Building dependency graphs to determine which files are affected by changes
74
- **Snapshot Integration**: Special handling for Jest snapshot files and their associated test files
75
- **Transitive Analysis**: Computing complete dependency chains for impact analysis
76

77
## Capabilities
78

79
### Module Dependency Resolution
80

81
Resolves direct dependencies of a given file, including both regular modules and Jest mock modules.
82

83
```typescript { .api }
84
/**
85
 * Resolves direct dependencies of a given file
86
 * @param file - Absolute path to the file to resolve dependencies for
87
 * @param options - Optional module resolution configuration
88
 * @returns Array of resolved dependency file paths
89
 */
90
resolve(file: string, options?: ResolveModuleConfig): Array<string>;
91
```
92

93
### Inverse Dependency Analysis
94

95
Determines which files depend on a set of changed files, essential for Jest's watch mode functionality.
96

97
```typescript { .api }
98
/**
99
 * Resolves inverse dependencies returning only file paths
100
 * @param paths - Set of file paths that have changed
101
 * @param filter - Function to filter which files to include in results
102
 * @param options - Optional module resolution configuration
103
 * @returns Array of file paths that depend on the changed files
104
 */
105
resolveInverse(
106
  paths: Set<string>,
107
  filter: (file: string) => boolean,
108
  options?: ResolveModuleConfig
109
): Array<string>;
110
```
111

112
### Detailed Inverse Dependency Mapping
113

114
Provides detailed module information including both files and their dependencies for comprehensive analysis.
115

116
```typescript { .api }
117
/**
118
 * Resolves inverse dependencies with detailed module information
119
 * @param paths - Set of file paths that have changed
120
 * @param filter - Function to filter which files to include in results
121
 * @param options - Optional module resolution configuration
122
 * @returns Array of resolved modules with dependencies
123
 */
124
resolveInverseModuleMap(
125
  paths: Set<string>,
126
  filter: (file: string) => boolean,
127
  options?: ResolveModuleConfig
128
): Array<ResolvedModule>;
129
```
130

131
## Types
132

133
```typescript { .api }
134
/**
135
 * Represents a resolved module with its file path and dependencies
136
 */
137
type ResolvedModule = {
138
  /** Absolute file path of the module */
139
  file: string;
140
  /** Array of resolved dependency file paths */
141
  dependencies: Array<string>;
142
};
143

144
/**
145
 * Main class for dependency resolution in Jest
146
 */
147
class DependencyResolver {
148
  /**
149
   * Creates a new DependencyResolver instance
150
   * @param resolver - Jest resolver instance for module resolution
151
   * @param hasteFS - Jest Haste file system interface
152
   * @param snapshotResolver - Jest snapshot resolver instance
153
   */
154
  constructor(
155
    resolver: Resolver,
156
    hasteFS: IHasteFS,
157
    snapshotResolver: SnapshotResolver
158
  );
159

160
  resolve(file: string, options?: ResolveModuleConfig): Array<string>;
161
  
162
  resolveInverse(
163
    paths: Set<string>,
164
    filter: (file: string) => boolean,
165
    options?: ResolveModuleConfig
166
  ): Array<string>;
167
  
168
  resolveInverseModuleMap(
169
    paths: Set<string>,
170
    filter: (file: string) => boolean,
171
    options?: ResolveModuleConfig
172
  ): Array<ResolvedModule>;
173
}
174

175
/**
176
 * Module resolution configuration options (from jest-resolve)
177
 */
178
interface ResolveModuleConfig {
179
  conditions?: Array<string>;
180
  [key: string]: any;
181
}
182
```
183

184
## Usage Examples
185

186
### Finding Test Files Affected by Changes
187

188
```typescript
189
import { DependencyResolver } from "jest-resolve-dependencies";
190

191
// Typical usage in Jest watch mode
192
const changedSourceFiles = new Set([
193
  "/project/src/utils.js",
194
  "/project/src/api/client.js"
195
]);
196

197
// Find all test files that need to re-run
198
const testFilter = (file: string) => 
199
  file.includes('__tests__') || 
200
  file.includes('.test.') || 
201
  file.includes('.spec.');
202

203
const affectedTests = dependencyResolver.resolveInverse(
204
  changedSourceFiles,
205
  testFilter
206
);
207

208
console.log("Tests to re-run:", affectedTests);
209
// Output: ["/project/src/__tests__/utils.test.js", "/project/src/api/__tests__/client.test.js"]
210
```
211

212
### Analyzing Module Dependencies
213

214
```typescript
215
// Get all direct dependencies of a module
216
const modulePath = "/project/src/components/Button.js";
217
const dependencies = dependencyResolver.resolve(modulePath);
218

219
console.log("Direct dependencies:", dependencies);
220
// Output: ["/project/src/styles.css", "/project/src/utils/helpers.js", "/project/node_modules/react/index.js"]
221
```
222

223
### Building Dependency Maps
224

225
```typescript
226
// Get detailed dependency information for impact analysis
227
const changedFiles = new Set(["/project/src/config.js"]);
228
const allFiles = (file: string) => true; // Include all file types
229

230
const dependencyMap = dependencyResolver.resolveInverseModuleMap(
231
  changedFiles,
232
  allFiles
233
);
234

235
dependencyMap.forEach(module => {
236
  console.log(`${module.file} depends on:`, module.dependencies);
237
});
238
```
239

240
### Working with Snapshots
241

242
```typescript
243
// The resolver automatically handles snapshot files
244
const snapshotFile = "/project/src/__tests__/__snapshots__/Button.test.js.snap";
245
const changedSnapshots = new Set([snapshotFile]);
246

247
// Find test files associated with changed snapshots
248
const relatedTests = dependencyResolver.resolveInverse(
249
  changedSnapshots,
250
  (file) => file.endsWith('.test.js')
251
);
252

253
console.log("Tests for changed snapshots:", relatedTests);
254
// Output: ["/project/src/__tests__/Button.test.js"]
255
```
256

257
## Integration with Jest
258

259
This package is primarily used internally by Jest for:
260

261
- **Watch Mode**: Determining which tests to re-run when files change
262
- **Dependency Tracking**: Building dependency graphs for test environments  
263
- **Mock Resolution**: Handling Jest mock modules in dependency analysis
264
- **Snapshot Testing**: Resolving relationships between snapshots and test files
265
- **Impact Analysis**: Understanding how changes propagate through the codebase
266

267
The DependencyResolver integrates with Jest's core systems including the Haste file system, module resolver, and snapshot resolver to provide comprehensive dependency analysis capabilities.
268

269
**For most users**: You don't need to use this package directly. Jest automatically uses it internally for dependency resolution during test execution and watch mode. This documentation is primarily useful for Jest plugin developers or those building custom testing tools that need direct access to Jest's dependency resolution capabilities.