0
# Jest Util
1

2
Jest Util is a comprehensive collection of utility functions specifically designed for the Jest testing framework ecosystem. It provides essential utilities for error handling, file system operations, terminal interactions, module loading compatibility, data manipulation, path and glob pattern matching, assertions and type checking, formatting utilities, global environment setup, and performance optimization through garbage collection utilities.
3

4
## Package Information
5

6
- **Package Name**: jest-util
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install jest-util`
10
- **Version**: 30.0.5
11

12
## Core Imports
13

14
```typescript
15
import { 
16
  clearLine, 
17
  createDirectory, 
18
  ErrorWithStack, 
19
  isInteractive, 
20
  isPromise,
21
  deepCyclicCopy,
22
  formatTime,
23
  pluralize
24
} from "jest-util";
25
```
26

27
For CommonJS:
28

29
```javascript
30
const { 
31
  clearLine, 
32
  createDirectory, 
33
  ErrorWithStack, 
34
  isInteractive, 
35
  isPromise,
36
  deepCyclicCopy,
37
  formatTime,
38
  pluralize
39
} = require("jest-util");
40
```
41

42
Namespace imports:
43

44
```typescript
45
import { specialChars, preRunMessage } from "jest-util";
46
```
47

48
## Basic Usage
49

50
```typescript
51
import { 
52
  createDirectory, 
53
  isPromise, 
54
  formatTime, 
55
  deepCyclicCopy,
56
  ErrorWithStack 
57
} from "jest-util";
58

59
// File system operations
60
createDirectory("/path/to/test/directory");
61

62
// Type checking
63
const maybePromise = someFunction();
64
if (isPromise(maybePromise)) {
65
  await maybePromise;
66
}
67

68
// Data utilities
69
const original = { nested: { data: [1, 2, 3] } };
70
const copy = deepCyclicCopy(original);
71

72
// Time formatting for test results
73
const executionTime = 1250; // milliseconds
74
console.log(`Test completed in ${formatTime(executionTime)}`); // "1.25 s"
75

76
// Error handling with stack traces
77
throw new ErrorWithStack("Test failed", testFunction);
78
```
79

80
## Architecture
81

82
Jest Util is organized around several key functional areas:
83

84
- **File System Utilities**: Safe directory creation and path resolution for test environments
85
- **Module Loading**: Cross-platform module loading with CommonJS/ES6 interoperability
86
- **Global Environment**: Jest test environment setup and global object management
87
- **Type Checking**: Runtime type validation and assertions for test data
88
- **Data Manipulation**: Deep copying and object utilities for test fixtures
89
- **String & Path Utilities**: Text formatting and path manipulation for test output
90
- **Terminal Interaction**: TTY detection and terminal output control
91
- **Garbage Collection**: Memory management and cleanup for test isolation
92

93
## Capabilities
94

95
### File System Utilities
96

97
Core file system operations designed for Jest's testing needs, including safe directory creation and path resolution.
98

99
```typescript { .api }
100
function createDirectory(path: string): void;
101
function tryRealpath(path: string): string;
102
```
103

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

106
### Module Loading Utilities
107

108
Cross-platform module loading utilities that handle CommonJS/ES6 interoperability and dynamic imports for Jest's module system.
109

110
```typescript { .api }
111
function interopRequireDefault(obj: any): any;
112
function requireOrImportModule<T>(
113
  filePath: string, 
114
  applyInteropRequireDefault?: boolean
115
): Promise<T>;
116
```
117

118
[Module Loading Utilities](./module-loading.md)
119

120
### Global Environment Management
121

122
Utilities for setting up and managing Jest's global test environment, including process object creation and global property management.
123

124
```typescript { .api }
125
function installCommonGlobals(
126
  globalObject: typeof globalThis,
127
  globals: Config.ConfigGlobals,
128
  garbageCollectionDeletionMode?: DeletionMode
129
): typeof globalThis & Config.ConfigGlobals;
130

131
function setGlobal(
132
  globalToMutate: typeof globalThis | Global.Global,
133
  key: string | symbol,
134
  value: unknown,
135
  afterTeardown: 'clean' | 'retain' = 'clean'
136
): void;
137
```
138

139
[Global Environment Management](./global-environment.md)
140

141
### Type Checking & Validation
142

143
Runtime type checking and validation utilities for test data and assertions.
144

145
```typescript { .api }
146
function isPromise<T = unknown>(candidate: unknown): candidate is PromiseLike<T>;
147
function isNonNullable<T>(value: T): value is NonNullable<T>;
148
function invariant(condition: unknown, message = ''): asserts condition;
149
```
150

151
[Type Checking & Validation](./type-checking.md)
152

153
### Data Manipulation
154

155
Utilities for copying, transforming, and manipulating data structures commonly used in test scenarios.
156

157
```typescript { .api }
158
function deepCyclicCopy<T>(
159
  value: T, 
160
  options?: DeepCyclicCopyOptions, 
161
  cycles?: WeakMap<any, any>
162
): T;
163

164
function convertDescriptorToString(
165
  descriptor: Global.BlockNameLike | undefined
166
): string;
167
```
168

169
[Data Manipulation](./data-manipulation.md)
170

171
### String & Path Utilities
172

173
Text formatting and path manipulation utilities for test output and file system operations.
174

175
```typescript { .api }
176
function pluralize(word: string, count: number, ending = 's'): string;
177
function formatTime(time: number, prefixPower = -3, padLeftLength = 0): string;
178
function replacePathSepForGlob(path: string): string;
179
function globsToMatcher(globs: Array<string>): Matcher;
180
```
181

182
[String & Path Utilities](./string-path.md)
183

184
### Terminal Interaction
185

186
Terminal and TTY interaction utilities for Jest's interactive features and output control.
187

188
```typescript { .api }
189
function clearLine(stream: WriteStream): void;
190
const isInteractive: boolean;
191
const specialChars: {
192
  ARROW: string;
193
  ICONS: {
194
    failed: string;
195
    pending: string;
196
    success: string;
197
    todo: string;
198
  };
199
  CLEAR: string;
200
};
201
const preRunMessage: {
202
  print(stream: WriteStream): void;
203
  remove(stream: WriteStream): void;
204
};
205
```
206

207
[Terminal Interaction](./terminal.md)
208

209
### Error Handling
210

211
Enhanced error handling with custom stack trace management for better test debugging.
212

213
```typescript { .api }
214
class ErrorWithStack extends Error {
215
  constructor(
216
    message: string | undefined,
217
    callsite: (...args: Array<any>) => unknown,
218
    stackLimit?: number
219
  );
220
}
221
```
222

223
[Error Handling](./error-handling.md)
224

225
### Garbage Collection Utilities
226

227
Memory management and cleanup utilities for test isolation and performance optimization.
228

229
```typescript { .api }
230
type DeletionMode = 'soft' | 'off' | 'on';
231

232
function initializeGarbageCollectionUtils(
233
  globalObject: typeof globalThis,
234
  deletionMode: DeletionMode
235
): void;
236

237
function canDeleteProperties(value: unknown): value is object;
238
function protectProperties<T>(
239
  value: T,
240
  properties?: Array<keyof T>,
241
  depth?: number
242
): boolean;
243
function deleteProperties(value: unknown): void;
244
```
245

246
[Garbage Collection Utilities](./garbage-collection.md)
247

248
## Core Types
249

250
```typescript { .api }
251
interface DeepCyclicCopyOptions {
252
  blacklist?: Set<string>;
253
  keepPrototype?: boolean;
254
}
255

256
type Matcher = (str: string) => boolean;
257

258
type DeletionMode = 'soft' | 'off' | 'on';
259
```