0
# Module Loading Utilities
1
2
Cross-platform module loading utilities that handle CommonJS/ES6 interoperability and dynamic imports for Jest's module system. These utilities ensure consistent module loading behavior across different Node.js versions and module formats.
3
4
## Capabilities
5
6
### Interop Require Default
7
8
Provides CommonJS and ES6 module interoperability, handling the default export pattern used by Babel and TypeScript transpilation.
9
10
```typescript { .api }
11
/**
12
* Provides CommonJS/ES6 module interoperability helper
13
* @param obj - Module object to check for default export pattern
14
* @returns obj.default if ES module format, otherwise {default: obj}
15
*/
16
function interopRequireDefault(obj: any): any;
17
```
18
19
**Usage Examples:**
20
21
```typescript
22
import { interopRequireDefault } from "jest-util";
23
24
// Handle transpiled ES6 modules loaded via require()
25
const moduleFromRequire = require("./some-es6-module");
26
const normalized = interopRequireDefault(moduleFromRequire);
27
28
// If moduleFromRequire has a 'default' property (ES6 module)
29
// Returns: moduleFromRequire.default
30
// If moduleFromRequire is a plain CommonJS export
31
// Returns: { default: moduleFromRequire }
32
33
// Common Jest use case - loading test modules consistently
34
const testModule = interopRequireDefault(require("./test-helper"));
35
const helper = testModule.default; // Always works regardless of module format
36
```
37
38
### Require Or Import Module
39
40
Dynamically loads modules using the appropriate method (`require()` or `import()`) based on file type and Node.js capabilities, with proper error handling and interop support.
41
42
```typescript { .api }
43
/**
44
* Dynamically loads modules using require() or import() based on file type
45
* @param filePath - Absolute path to module file
46
* @param applyInteropRequireDefault - Whether to apply interop transformation (default: true)
47
* @returns Promise resolving to the loaded module
48
* @throws Error with helpful message if module loading fails
49
*/
50
function requireOrImportModule<T>(
51
filePath: string,
52
applyInteropRequireDefault?: boolean
53
): Promise<T>;
54
```
55
56
**Usage Examples:**
57
58
```typescript
59
import { requireOrImportModule } from "jest-util";
60
61
// Load configuration files dynamically
62
const jestConfig = await requireOrImportModule<any>("./jest.config.js");
63
64
// Load test modules with type safety
65
interface TestSuite {
66
describe: string;
67
tests: Array<{ name: string; fn: () => void }>;
68
}
69
const testSuite = await requireOrImportModule<TestSuite>("./my-test.mjs");
70
71
// Skip interop transformation for certain modules
72
const rawModule = await requireOrImportModule("./raw-module.js", false);
73
74
// Handle different file extensions automatically
75
const tsConfig = await requireOrImportModule("./tsconfig.json"); // Uses require
76
const esmModule = await requireOrImportModule("./module.mjs"); // Uses import()
77
```
78
79
**Behavior:**
80
- **CommonJS files (`.js`, `.json`)**: Uses `require()` for synchronous loading
81
- **ES Module files (`.mjs`, `.js` in ESM context)**: Uses dynamic `import()`
82
- **TypeScript files**: Handles based on compilation target and Node.js version
83
- **Error handling**: Provides clear error messages distinguishing between file not found, syntax errors, and import failures
84
- **Interop handling**: Automatically applies `interopRequireDefault` unless explicitly disabled
85
86
**Error Scenarios:**
87
88
```typescript
89
// File not found
90
try {
91
await requireOrImportModule("./non-existent.js");
92
} catch (error) {
93
// Clear error message about missing file
94
}
95
96
// Syntax error in module
97
try {
98
await requireOrImportModule("./broken-syntax.js");
99
} catch (error) {
100
// Error includes module path and syntax details
101
}
102
103
// ES Module in CommonJS context
104
try {
105
await requireOrImportModule("./esm-only.mjs");
106
} catch (error) {
107
// Falls back to import() with helpful context
108
}
109
```