0
# Istanbul Lib Instrument
1

2
Istanbul Lib Instrument is the core Istanbul API for JavaScript code coverage instrumentation. It transforms JavaScript code by adding coverage tracking capabilities using Babel AST transformations, enabling comprehensive line, branch, and function coverage analysis for testing frameworks.
3

4
## Package Information
5

6
- **Package Name**: istanbul-lib-instrument
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install istanbul-lib-instrument`
10

11
## Core Imports
12

13
```javascript
14
const { createInstrumenter, programVisitor, readInitialCoverage, defaultOpts } = require("istanbul-lib-instrument");
15
```
16

17
For ES modules:
18

19
```javascript
20
import { createInstrumenter, programVisitor, readInitialCoverage, defaultOpts } from "istanbul-lib-instrument";
21
```
22

23
## Basic Usage
24

25
```javascript
26
const { createInstrumenter } = require("istanbul-lib-instrument");
27

28
// Create an instrumenter with default options
29
const instrumenter = createInstrumenter();
30

31
// Instrument JavaScript code
32
const code = 'function add(a, b) { return a + b; }';
33
const instrumentedCode = instrumenter.instrumentSync(code, 'math.js');
34

35
// Get coverage data for the last instrumented file
36
const coverage = instrumenter.lastFileCoverage();
37
console.log(coverage);
38
```
39

40
## Architecture
41

42
Istanbul Lib Instrument provides two primary instrumentation approaches:
43

44
- **Legacy API**: Direct instrumenter usage with `createInstrumenter()` and `Instrumenter` class for standalone instrumentation
45
- **Babel Plugin Integration**: `programVisitor` function for direct integration with Babel plugins like `babel-plugin-istanbul`
46
- **Coverage Reading**: `readInitialCoverage` utility for extracting existing coverage data from already instrumented code
47
- **AST Processing**: Deep integration with Babel's AST manipulation for precise code transformation
48
- **Source Map Support**: Full source map preservation and generation for debugging instrumented code
49

50
## Capabilities
51

52
### Code Instrumentation
53

54
Primary instrumenter functionality for transforming JavaScript code with coverage tracking. Supports both synchronous and callback-style instrumentation with extensive configuration options.
55

56
```javascript { .api }
57
function createInstrumenter(opts?: InstrumenterOptions): Instrumenter;
58

59
interface InstrumenterOptions {
60
  coverageVariable?: string;
61
  reportLogic?: boolean;
62
  preserveComments?: boolean;
63
  compact?: boolean;
64
  esModules?: boolean;
65
  autoWrap?: boolean;
66
  produceSourceMap?: boolean;
67
  ignoreClassMethods?: string[];
68
  sourceMapUrlCallback?: (filename: string, url: string) => void;
69
  debug?: boolean;
70
  parserPlugins?: string[];
71
  coverageGlobalScope?: string;
72
  coverageGlobalScopeFunc?: boolean;
73
  generatorOpts?: object;
74
}
75

76
class Instrumenter {
77
  instrumentSync(code: string, filename: string, inputSourceMap?: object): string;
78
  instrument(code: string, filename: string, callback: (err: Error | null, result: string) => void, inputSourceMap?: object): void;
79
  lastFileCoverage(): object;
80
  lastSourceMap(): object | null;
81
}
82
```
83

84
[Instrumentation](./instrumentation.md)
85

86
### Babel Plugin Integration
87

88
Programmatic visitor function for integrating coverage instrumentation directly into Babel transformation pipelines. Used by babel-plugin-istanbul and other Babel-based tools.
89

90
```javascript { .api }
91
function programVisitor(
92
  types: object,
93
  sourceFilePath?: string,
94
  opts?: ProgramVisitorOptions
95
): ProgramVisitorResult;
96

97
interface ProgramVisitorOptions {
98
  coverageVariable?: string;
99
  reportLogic?: boolean;
100
  coverageGlobalScope?: string;
101
  coverageGlobalScopeFunc?: boolean;
102
  ignoreClassMethods?: string[];
103
  inputSourceMap?: object;
104
}
105

106
interface ProgramVisitorResult {
107
  enter(path: object): void;
108
  exit(path: object): { fileCoverage: object; sourceMappingURL?: string };
109
}
110
```
111

112
[Babel Integration](./babel-integration.md)
113

114
### Coverage Data Reading
115

116
Utility for extracting existing coverage data from already instrumented JavaScript code, enabling coverage analysis of pre-instrumented files.
117

118
```javascript { .api }
119
function readInitialCoverage(code: string | object): CoverageData | null;
120

121
interface CoverageData {
122
  path: string;
123
  hash: string;
124
  gcv: string;
125
  coverageData: object;
126
}
127
```
128

129
[Coverage Reading](./coverage-reading.md)
130

131
## Types
132

133
```javascript { .api }
134
// Default instrumenter options from @istanbuljs/schema
135
const defaultOpts: InstrumenterOptions;
136

137
// Coverage variable scope types
138
type CoverageScope = "this" | "global" | "window" | string;
139

140
// Parser plugin names for Babel
141
type ParserPlugin = string;
142

143
// Source map callback function type
144
type SourceMapCallback = (filename: string, url: string) => void;
145
```