0
# Istanbul Lib Source Maps
1

2
Istanbul Lib Source Maps provides source map support for the Istanbul code coverage toolkit, enabling accurate coverage reporting for transpiled JavaScript code. It manages source map resolution and transformation to map coverage data from generated code back to original source files, supporting various source map formats and providing utilities for storing, retrieving, and processing source map information.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const { createSourceMapStore } = require("istanbul-lib-source-maps");
15
```
16

17
For internal classes (not typically needed by end users):
18

19
```javascript
20
const { MapStore } = require("istanbul-lib-source-maps/lib/map-store");
21
const { SourceMapTransformer } = require("istanbul-lib-source-maps/lib/transformer");
22
const { MappedCoverage } = require("istanbul-lib-source-maps/lib/mapped");
23
```
24

25
## Basic Usage
26

27
```javascript
28
const { createSourceMapStore } = require("istanbul-lib-source-maps");
29

30
// Create a source map store
31
const store = createSourceMapStore({
32
  verbose: false,
33
  baseDir: process.cwd()
34
});
35

36
// Register source maps
37
store.registerURL('/path/to/built/file.js', './file.js.map');
38
store.registerMap('/path/to/built/file.js', sourceMapObject);
39

40
// Transform coverage to original sources
41
const transformedCoverage = await store.transformCoverage(coverageMap);
42

43
// Clean up resources
44
store.dispose();
45
```
46

47
## Architecture
48

49
Istanbul Lib Source Maps is built around several key components:
50

51
- **MapStore**: Central registry for source maps, handles registration, retrieval, and coverage transformation
52
- **SourceMapTransformer**: Core engine that processes coverage data through source maps
53
- **MappedCoverage**: Specialized coverage object that accumulates mapped statements, functions, and branches
54
- **Utility Functions**: Helper functions for source mapping, path resolution, and data transformation
55

56
## Capabilities
57

58
### Source Map Store Factory
59

60
Creates and configures source map stores for tracking and transforming coverage data.
61

62
```javascript { .api }
63
/**
64
 * Creates a new MapStore instance for tracking source maps
65
 * @param {Object} opts - Configuration options for the MapStore
66
 * @returns {MapStore} MapStore instance
67
 */
68
function createSourceMapStore(opts);
69
```
70

71
### MapStore Class
72

73
Central class for managing source maps and transforming coverage data to original sources.
74

75
```javascript { .api }
76
class MapStore {
77
  /**
78
   * @param {Object} opts - Configuration options
79
   * @param {Boolean} opts.verbose - Enable verbose logging (default: false)
80
   * @param {String} opts.baseDir - Alternate base directory for sourcemap resolution (default: null)
81
   * @param {Class} opts.SourceStore - Class for source storage (default: Map)
82
   * @param {Array} opts.sourceStoreOpts - Arguments for SourceStore constructor (default: [])
83
   */
84
  constructor(opts);
85

86
  /**
87
   * Registers a source map URL with this store
88
   * @param {String} transformedFilePath - File path for which the source map is valid
89
   * @param {String} sourceMapUrl - Source map URL (not a comment)
90
   */
91
  registerURL(transformedFilePath, sourceMapUrl);
92

93
  /**
94
   * Registers a source map object with this store
95
   * @param {String} transformedFilePath - File path for which the source map is valid
96
   * @param {Object} sourceMap - Source map object with version property
97
   */
98
  registerMap(transformedFilePath, sourceMap);
99

100
  /**
101
   * Retrieve a source map object from this store synchronously
102
   * @param {String} filePath - File path to get source map for
103
   * @returns {Object|undefined} Parsed source map object or undefined if not found
104
   */
105
  getSourceMapSync(filePath);
106

107
  /**
108
   * Add inputSourceMap property to coverage data entries
109
   * @param {Object} coverageData - The __coverage__ object
110
   */
111
  addInputSourceMapsSync(coverageData);
112

113
  /**
114
   * Transforms coverage map to refer to original sources using registered mappings
115
   * @param {CoverageMap} coverageMap - Coverage map to transform
116
   * @returns {Promise<CoverageMap>} Transformed coverage map
117
   */
118
  async transformCoverage(coverageMap);
119

120
  /**
121
   * Disposes temporary resources allocated by this map store
122
   */
123
  dispose();
124

125
  /**
126
   * Internal method to find source content for a file path
127
   * @param {String} filePath - Path to source file
128
   * @returns {String} Source file content
129
   */
130
  sourceFinder(filePath);
131
}
132
```
133

134
### SourceMapTransformer Class
135

136
Core transformation engine that processes coverage data through source maps.
137

138
```javascript { .api }
139
class SourceMapTransformer {
140
  /**
141
   * @param {Function} finder - Async function to find source maps for files
142
   * @param {Object} opts - Options including baseDir and custom getMapping function
143
   * @param {String} opts.baseDir - Base directory for path resolution (default: process.cwd())
144
   * @param {Function} opts.getMapping - Custom mapping function (default: built-in getMapping)
145
   */
146
  constructor(finder, opts);
147

148
  /**
149
   * Transform a coverage map using source maps
150
   * @param {CoverageMap} coverageMap - Coverage map to transform
151
   * @returns {Promise<CoverageMap>} Transformed coverage map
152
   */
153
  async transform(coverageMap);
154

155
  /**
156
   * Process a single file's coverage data with its source map
157
   * @param {FileCoverage} fc - File coverage object
158
   * @param {SourceMap} sourceMap - Source map for the file
159
   * @param {Function} coverageMapper - Function to get mapped coverage for a source file
160
   * @returns {Boolean} Whether any changes were made
161
   */
162
  processFile(fc, sourceMap, coverageMapper);
163
}
164
```
165

166
### MappedCoverage Class
167

168
Specialized coverage object that accumulates mapped statements, functions, and branches from source-mapped files.
169

170
```javascript { .api }
171
class MappedCoverage extends FileCoverage {
172
  /**
173
   * @param {String|Object} pathOrObj - File path or existing coverage object
174
   */
175
  constructor(pathOrObj);
176

177
  /**
178
   * Add a statement mapping with hit count
179
   * @param {Object} loc - Location object with start/end positions
180
   * @param {Number} hits - Number of times statement was hit
181
   * @returns {Number} Statement index
182
   */
183
  addStatement(loc, hits);
184

185
  /**
186
   * Add a function mapping with hit count
187
   * @param {String} name - Function name (auto-generated if not provided)
188
   * @param {Object} decl - Declaration location object
189
   * @param {Object} loc - Function body location object
190
   * @param {Number} hits - Number of times function was called
191
   * @returns {Number} Function index
192
   */
193
  addFunction(name, decl, loc, hits);
194

195
  /**
196
   * Add a branch mapping with hit counts
197
   * @param {String} type - Branch type (e.g., 'if', 'switch')
198
   * @param {Object} loc - Branch location object
199
   * @param {Array<Object>} branchLocations - Array of branch location objects
200
   * @param {Array<Number>} hits - Array of hit counts for each branch
201
   * @returns {Number} Branch index
202
   */
203
  addBranch(type, loc, branchLocations, hits);
204

205
  /**
206
   * Clone a location object with only essential attributes
207
   * @param {Object} loc - Location object to clone
208
   * @returns {Object} Cloned location object with start/end properties
209
   */
210
  cloneLocation(loc);
211
}
212
```
213

214
### Utility Functions
215

216
Helper functions for source mapping, path resolution, and data transformation.
217

218
```javascript { .api }
219
/**
220
 * Determines original position for a generated location using source map
221
 * @param {SourceMap} sourceMap - Source map object
222
 * @param {Object} generatedLocation - Generated location with start/end positions
223
 * @param {String} origFile - Original file path
224
 * @returns {Object|null} Mapping object with source and loc properties, or null
225
 */
226
function getMapping(sourceMap, generatedLocation, origFile);
227

228
/**
229
 * Generate unique key from pathname by replacing slashes
230
 * @param {String} pathname - File pathname
231
 * @returns {String} Unique key with slashes replaced by underscores
232
 */
233
function getUniqueKey(pathname);
234

235
/**
236
 * Convert cache object to output format for coverage data
237
 * @param {Object} cache - Cache with file/mappedCoverage entries
238
 * @returns {Object} Coverage output object
239
 */
240
function getOutput(cache);
241

242
/**
243
 * Check if path is absolute
244
 * @param {String} file - File path
245
 * @returns {Boolean} True if path is absolute
246
 */
247
function isAbsolute(file);
248

249
/**
250
 * Convert relative path to absolute using baseDir
251
 * @param {String} file - File path
252
 * @param {String} baseDir - Base directory (defaults to process.cwd())
253
 * @returns {String} Absolute file path
254
 */
255
function asAbsolute(file, baseDir);
256

257
/**
258
 * Resolve file path relative to origFile directory
259
 * @param {String} file - File path to resolve
260
 * @param {String} origFile - Original file to resolve relative to
261
 * @returns {String} Resolved file path
262
 */
263
function relativeTo(file, origFile);
264
```
265

266
## Types
267

268
```javascript { .api }
269
/**
270
 * Configuration options for MapStore
271
 */
272
interface MapStoreOptions {
273
  verbose?: boolean;           // Enable verbose logging (default: false)
274
  baseDir?: string;           // Alternate base directory (default: null)
275
  SourceStore?: Class;        // Storage class (default: Map)
276
  sourceStoreOpts?: Array;    // Storage constructor arguments (default: [])
277
}
278

279
/**
280
 * Location object representing code positions
281
 */
282
interface Location {
283
  start: {
284
    line: number;
285
    column: number;
286
  };
287
  end: {
288
    line: number;
289
    column: number;
290
  };
291
}
292

293
/**
294
 * Source map mapping result
295
 */
296
interface MappingResult {
297
  source: string;      // Original source file path
298
  loc: Location;       // Location in original source
299
}
300

301
/**
302
 * Coverage map interface (from istanbul-lib-coverage)
303
 */
304
interface CoverageMap {
305
  files(): Array<string>;
306
  fileCoverageFor(file: string): FileCoverage;
307
}
308

309
/**
310
 * File coverage interface (from istanbul-lib-coverage)
311
 */
312
interface FileCoverage {
313
  path: string;
314
  statementMap: Object;
315
  fnMap: Object;
316
  branchMap: Object;
317
  s: Object;          // Statement hit counts
318
  f: Object;          // Function hit counts
319
  b: Object;          // Branch hit counts
320
  data: Object;       // Raw coverage data
321
}
322
```
323

324
## Error Handling
325

326
The library handles various error conditions gracefully:
327

328
- **Invalid source maps**: Silently fails registration and logs debug messages
329
- **Missing source map files**: Returns undefined from getSourceMapSync()
330
- **Malformed URLs**: Ignores invalid data URLs and file paths
331
- **Source mapping failures**: Skips unmappable locations and continues processing
332
- **File system errors**: Catches and logs errors when reading source map files
333

334
Enable debug logging with `DEBUG=istanbuljs` environment variable to see detailed error information.
335

336
## Usage Examples
337

338
### Complete Integration Example
339

340
```javascript
341
const libCoverage = require('istanbul-lib-coverage');
342
const { createSourceMapStore } = require('istanbul-lib-source-maps');
343

344
async function processCoverage(coverageData) {
345
  // Create coverage map from raw coverage data
346
  const coverageMap = libCoverage.createCoverageMap(coverageData);
347
  
348
  // Create source map store
349
  const store = createSourceMapStore({
350
    verbose: true,
351
    baseDir: '/project/root'
352
  });
353
  
354
  // Register source maps for transformed files
355
  store.registerURL('/build/app.js', '/build/app.js.map');
356
  store.registerURL('/build/utils.js', '/build/utils.js.map');
357
  
358
  // Transform coverage to original sources
359
  const transformedCoverage = await store.transformCoverage(coverageMap);
360
  
361
  // Clean up
362
  store.dispose();
363
  
364
  return transformedCoverage;
365
}
366
```
367

368
### Manual Source Map Registration
369

370
```javascript
371
const fs = require('fs');
372
const { createSourceMapStore } = require('istanbul-lib-source-maps');
373

374
const store = createSourceMapStore();
375

376
// Register from file
377
const sourceMapContent = fs.readFileSync('./dist/bundle.js.map', 'utf8');
378
const sourceMapObject = JSON.parse(sourceMapContent);
379
store.registerMap('./dist/bundle.js', sourceMapObject);
380

381
// Register inline source map
382
store.registerURL('./dist/inline.js', 
383
  'data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjo...');
384

385
// Register external source map
386
store.registerURL('./dist/external.js', './external.js.map');
387
```