0
# Jest Leak Detector
1

2
Jest Leak Detector is a TypeScript utility for verifying whether an object has been garbage collected or not. It creates weak references to objects and forces garbage collection to determine if objects are properly released from memory. This library is primarily used within the Jest testing framework ecosystem for memory leak detection during test execution.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import LeakDetector from "jest-leak-detector";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const LeakDetector = require("jest-leak-detector");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import LeakDetector from "jest-leak-detector";
27

28
async function detectLeak() {
29
  let reference = { data: "some object" };
30
  
31
  // Create detector to monitor the object
32
  const detector = new LeakDetector(reference);
33
  
34
  // Check if object is still in memory (should be true)
35
  let isLeaking = await detector.isLeaking();
36
  console.log(isLeaking); // true
37
  
38
  // Remove reference
39
  reference = null;
40
  
41
  // Check again after nullifying reference (should be false)
42
  isLeaking = await detector.isLeaking();
43
  console.log(isLeaking); // false
44
}
45
```
46

47
## Capabilities
48

49
### Leak Detection
50

51
Creates a leak detector that monitors whether a given object has been garbage collected.
52

53
```typescript { .api }
54
class LeakDetector {
55
  /**
56
   * Creates a leak detector for monitoring object garbage collection
57
   * @param value - The object to monitor (cannot be a primitive value)
58
   * @param opt - Optional configuration for detection behavior
59
   * @throws TypeError if value is a primitive (undefined, null, boolean, number, string, symbol)
60
   */
61
  constructor(value: unknown, opt?: LeakDetectorOptions);
62

63
  /**
64
   * Checks if the monitored object is still in memory
65
   * Forces garbage collection and checks if the object is still referenced
66
   * @returns Promise resolving to true if object is still in memory, false if garbage collected
67
   */
68
  isLeaking(): Promise<boolean>;
69
}
70
```
71

72
**Usage Examples:**
73

74
```typescript
75
// Monitor simple objects
76
const detector = new LeakDetector({ foo: "bar" });
77
const isLeaking = await detector.isLeaking();
78

79
// Monitor functions
80
const fn = () => console.log("test");
81
const fnDetector = new LeakDetector(fn);
82

83
// Monitor arrays
84
const arr = [1, 2, 3];
85
const arrDetector = new LeakDetector(arr);
86

87
// With configuration options
88
const detector = new LeakDetector(someObject, {
89
  shouldGenerateV8HeapSnapshot: false
90
});
91
```
92

93
### Configuration Options
94

95
Options for customizing leak detection behavior.
96

97
```typescript { .api }
98
interface LeakDetectorOptions {
99
  /**
100
   * Whether to generate V8 heap snapshots for more aggressive garbage collection
101
   * Heap snapshots provide more thorough GC but are slower to execute
102
   * @default true
103
   */
104
  shouldGenerateV8HeapSnapshot: boolean;
105
}
106
```
107

108
## Error Handling
109

110
The LeakDetector throws errors in the following cases:
111

112
- **TypeError**: When attempting to monitor primitive values (undefined, null, boolean, number, string, symbol)
113
  - Error format: `"Primitives cannot leak memory. You passed a {type}: <{formatted_value}>"`
114

115
```typescript
116
// These will throw TypeError
117
new LeakDetector(null);        // TypeError: Primitives cannot leak memory. You passed a object: <null>
118
new LeakDetector(42);          // TypeError: Primitives cannot leak memory. You passed a number: <42>
119
new LeakDetector("string");    // TypeError: Primitives cannot leak memory. You passed a string: <"string">
120
new LeakDetector(true);        // TypeError: Primitives cannot leak memory. You passed a boolean: <true>
121
new LeakDetector(undefined);   // TypeError: Primitives cannot leak memory. You passed a undefined: <undefined>
122
new LeakDetector(Symbol());    // TypeError: Primitives cannot leak memory. You passed a symbol: <Symbol()>
123
```
124

125
## Platform Requirements
126

127
- **Node.js**: ^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0
128
- **JavaScript Features**: ES2021.WeakRef (FinalizationRegistry support)
129
- **V8 Features**: Heap snapshots, garbage collector access
130

131
## Implementation Details
132

133
The leak detector uses several advanced JavaScript and Node.js features:
134

135
- **FinalizationRegistry**: Tracks object lifecycle and executes cleanup callbacks when objects are garbage collected
136
- **V8 Heap Snapshots**: Optional aggressive garbage collection through `v8.getHeapSnapshot()`
137
- **V8 Flags**: Temporarily exposes and hides the garbage collector via `--expose-gc` and `--no-expose-gc` flags
138
- **setImmediate Ticks**: Allows garbage collection cycles to complete before checking object status
139
- **VM Context**: Executes garbage collection in a new context to avoid reference leaks