0
# v8-to-istanbul
1

2
v8-to-istanbul converts V8 coverage format to Istanbul's coverage format, enabling developers to use V8's native code coverage data with Istanbul-compatible tools and reporters. It supports source map transformations, coverage ignores via special comments, and handles complex JavaScript module loading patterns.
3

4
## Package Information
5

6
- **Package Name**: v8-to-istanbul
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install v8-to-istanbul`
10
- **Node.js Compatibility**: >= 10.12.0
11

12
## Core Imports
13

14
```javascript
15
const v8ToIstanbul = require('v8-to-istanbul');
16
```
17

18
For ESM:
19

20
```javascript
21
import v8ToIstanbul from 'v8-to-istanbul';
22
```
23

24
For TypeScript:
25

26
```typescript
27
import v8ToIstanbul from 'v8-to-istanbul';
28
import type { Sources } from 'v8-to-istanbul';
29
```
30

31
## Basic Usage
32

33
```javascript
34
const v8ToIstanbul = require('v8-to-istanbul');
35

36
// Create converter instance for a source file
37
const converter = v8ToIstanbul('./path-to-file.js');
38

39
// Load the file and any source maps
40
await converter.load();
41

42
// Apply V8 coverage data
43
converter.applyCoverage([
44
  {
45
    "functionName": "",
46
    "ranges": [
47
      {
48
        "startOffset": 0,
49
        "endOffset": 520,
50
        "count": 1
51
      }
52
    ],
53
    "isBlockCoverage": true
54
  }
55
]);
56

57
// Convert to Istanbul format
58
const istanbulCoverage = converter.toIstanbul();
59
console.log(JSON.stringify(istanbulCoverage, null, 2));
60
```
61

62
## Capabilities
63

64
### Factory Function
65

66
Creates a new V8ToIstanbul converter instance.
67

68
```typescript { .api }
69
/**
70
 * Factory function to create a V8ToIstanbul converter instance
71
 * @param scriptPath - Path to the source file (supports file:// URLs)
72
 * @param wrapperLength - Length of module wrapper code (auto-detected for CommonJS)
73
 * @param sources - Optional sources configuration for providing content directly
74
 * @param excludePath - Optional function to exclude certain paths from coverage
75
 * @returns V8ToIstanbul converter instance
76
 */
77
declare function v8ToIstanbul(
78
  scriptPath: string, 
79
  wrapperLength?: number, 
80
  sources?: Sources, 
81
  excludePath?: (path: string) => boolean
82
): V8ToIstanbul;
83
```
84

85
### V8ToIstanbul Class
86

87
Main converter class that handles the transformation process.
88

89
```typescript { .api }
90
declare class V8ToIstanbul {
91
  /**
92
   * Loads and processes the source file, handles source maps
93
   * Must be called before applying coverage
94
   */
95
  load(): Promise<void>;
96

97
  /**
98
   * Applies V8 coverage data to the loaded source
99
   * @param blocks - Array of V8 coverage blocks from Node.js inspector
100
   */
101
  applyCoverage(blocks: ReadonlyArray<Profiler.FunctionCoverage>): void;
102

103
  /**
104
   * Converts processed coverage data to Istanbul format
105
   * @returns Istanbul-compatible coverage data
106
   */
107
  toIstanbul(): CoverageMapData;
108

109
  /**
110
   * Cleanup method (no longer necessary, preserved for backwards compatibility)
111
   */
112
  destroy(): void;
113
}
114
```
115

116
### Coverage Ignore Comments
117

118
The library supports special comments to exclude lines from coverage tracking:
119

120
```javascript
121
// Ignore the next line
122
/* v8 ignore next */
123
const platformSpecificCode = process.platform === 'win32' ? windowsCode() : defaultCode();
124

125
// Ignore the next N lines
126
/* v8 ignore next 3 */
127
if (process.platform === 'win32') {
128
  console.log('Windows detected');
129
}
130

131
// Ignore blocks of code
132
/* v8 ignore start */
133
function debugOnlyFunction() {
134
  // This entire function will be ignored
135
}
136
/* v8 ignore stop */
137

138
// Legacy c8 format is also supported
139
/* c8 ignore next */
140
/* c8 ignore next 2 */
141
/* c8 ignore start */
142
/* c8 ignore stop */
143

144
// Node.js native coverage comments
145
/* node:coverage disable */
146
function testHelperFunction() {
147
  // This function will be ignored
148
}
149
/* node:coverage enable */
150
```
151

152
## Types
153

154
```typescript { .api }
155
import { Profiler } from 'inspector';
156
import { CoverageMapData } from 'istanbul-lib-coverage';
157
import { SourceMapInput } from '@jridgewell/trace-mapping';
158

159
/**
160
 * Sources configuration for providing source content directly
161
 */
162
type Sources = 
163
  | { source: string }
164
  | { 
165
      source: string;
166
      originalSource: string;
167
      sourceMap: { sourcemap: SourceMapInput };
168
    };
169

170
/**
171
 * V8 function coverage data from Node.js inspector
172
 * This is the standard Profiler.FunctionCoverage interface
173
 */
174
type FunctionCoverage = Profiler.FunctionCoverage;
175

176
/**
177
 * Istanbul coverage map data structure
178
 * This is the standard CoverageMapData from istanbul-lib-coverage
179
 */
180
type CoverageMapDataType = CoverageMapData;
181
```
182

183
## Advanced Usage
184

185
### Working with Source Maps
186

187
```javascript
188
const v8ToIstanbul = require('v8-to-istanbul');
189

190
// For transpiled code with source maps
191
const converter = v8ToIstanbul('./dist/compiled.js');
192
await converter.load(); // Automatically detects and loads source maps
193

194
// Providing source content directly
195
const converter2 = v8ToIstanbul('./src/original.ts', 0, {
196
  source: transpiledSource,
197
  originalSource: originalSource,
198
  sourceMap: { sourcemap: sourceMapObject }
199
});
200
await converter2.load();
201
```
202

203
### Excluding Paths from Coverage
204

205
```javascript
206
const converter = v8ToIstanbul('./src/app.js', 0, null, (path) => {
207
  // Exclude test files and node_modules
208
  return path.includes('/test/') || path.includes('node_modules');
209
});
210
```
211

212
### ESM and File URLs
213

214
```javascript
215
import { pathToFileURL } from 'url';
216

217
// Handle ESM file paths
218
const converter = v8ToIstanbul(
219
  pathToFileURL('./src/module.mjs').href,
220
  0 // ESM has no wrapper
221
);
222
```
223

224
## Error Handling
225

226
The library throws errors for:
227
- Invalid script paths (non-string values)
228
- Node.js versions below 10.12.0
229
- File system errors when loading source files
230
- Invalid V8 coverage data structures
231

232
Common error scenarios:
233

234
```javascript
235
try {
236
  const converter = v8ToIstanbul('./non-existent-file.js');
237
  await converter.load();
238
} catch (error) {
239
  if (error.code === 'ENOENT') {
240
    console.error('Source file not found');
241
  }
242
}
243
```