@jridgewell/source-map

What is @jridgewell/source-map?

The @jridgewell/source-map package is designed for creating, parsing, and manipulating source maps, which are files that map from the transformed source to the original source, enabling the browser to reconstruct the original source and present it to the developer. This is particularly useful for debugging minified code or code compiled from languages like TypeScript.

What are @jridgewell/source-map's main functionalities?

Generating a source map

This feature allows you to generate a source map by specifying the version, the output file name, the sources involved, the names used in the mappings, and the mappings themselves. The mappings detail how segments of the source are transformed and correspond to the generated code.

{"version":3,"file":"out.js","sources":["foo.js","bar.js"],"names":["src","maps","are","fun"],"mappings":"AAgBC,SAAQ,CAAEA"}

Parsing a source map

This feature enables the parsing of a source map from a string. It's useful for further manipulation or analysis of the source map, such as extracting information about the original sources or mappings.

const sourceMap = require('@jridgewell/source-map');
let parsedMap = sourceMap.parse('{"version":3,"sources":["foo.js"],"names":[],"mappings":"AAAA;AACA;AACA"}');

Adding and removing mappings

This demonstrates how to add and remove mappings from a source map. This is useful for dynamic manipulation of the source map, such as when merging source maps or making adjustments to the mappings.

const generator = new sourceMap.SourceMapGenerator({file: "out.js"});
generator.addMapping({generated: {line: 1, column: 0}, original: {line: 1, column: 0}, source: "foo.js"});
generator.removeMapping({generated: {line: 1, column: 0}, source: "foo.js"});

Other packages similar to @jridgewell/source-map

source-map

The 'source-map' package provides similar functionalities for generating, parsing, and manipulating source maps. It is one of the most popular and widely used source map libraries. Compared to @jridgewell/source-map, it might offer a broader API surface and has been around for a longer time, making it more mature in some aspects.

source-map-js

source-map-js is a fork of the original 'source-map' library, intended to provide improvements and optimizations over the original. It aims to be fully API-compatible with 'source-map', offering an alternative with potentially better performance or bug fixes. The choice between this and @jridgewell/source-map might come down to specific needs regarding performance and API compatibility.

README

@jridgewell/source-map

Packages @jridgewell/trace-mapping and @jridgewell/gen-mapping into the familiar source-map API

This isn't the full API, but it's the core functionality. This wraps @jridgewell/trace-mapping and @jridgewell/gen-mapping implementations.

Installation

npm install @jridgewell/source-map

Usage

TODO

SourceMapConsumer

import { SourceMapConsumer } from '@jridgewell/source-map';
const smc = new SourceMapConsumer({
  version: 3,
  names: ['foo'],
  sources: ['input.js'],
  mappings: 'AAAAA',
});

SourceMapConsumer.fromSourceMap(mapGenerator[, mapUrl])

Transforms a SourceMapGenerator into a SourceMapConsumer.

const smg = new SourceMapGenerator();

const smc = SourceMapConsumer.fromSourceMap(map);
smc.originalPositionFor({ line: 1, column: 0 });

SourceMapConsumer.prototype.originalPositionFor(generatedPosition)

const smc = new SourceMapConsumer(map);
smc.originalPositionFor({ line: 1, column: 0 });

SourceMapConsumer.prototype.mappings

const smc = new SourceMapConsumer(map);
smc.mappings; // AAAA

SourceMapConsumer.prototype.allGeneratedPositionsFor(originalPosition)

const smc = new SourceMapConsumer(map);
smc.allGeneratedpositionsfor({ line: 1, column: 5, source: "baz.ts" });
// [
//   { line: 2, column: 8 }
// ]

SourceMapConsumer.prototype.eachMapping(callback[, context[, order]])

This implementation currently does not support the "order" parameter. This function can only iterate in Generated order.

const smc = new SourceMapConsumer(map);
smc.eachMapping((mapping) => {
// { source: 'baz.ts',
//   generatedLine: 4,
//   generatedColumn: 5,
//   originalLine: 4,
//   originalColumn: 5,
//   name: null }
});

SourceMapConsumer.prototype.generatedPositionFor(originalPosition)

const smc = new SourceMapConsumer(map);
smc.generatedPositionFor({ line: 1, column: 5, source: "baz.ts" });
// { line: 2, column: 8 }

SourceMapConsumer.prototype.hasContentsOfAllSources()

const smc = new SourceMapConsumer(map);
smc.hasContentsOfAllSources();
// true

SourceMapConsumer.prototype.sourceContentFor(source[, returnNullOnMissing])

const smc = new SourceMapConsumer(map);
smc.generatedPositionFor("baz.ts");
// "export default ..."

SourceMapConsumer.prototype.version

Returns the source map's version

SourceMapGenerator

import { SourceMapGenerator } from '@jridgewell/source-map';
const smg = new SourceMapGenerator({
  file: 'output.js',
  sourceRoot: 'https://example.com/',
});

SourceMapGenerator.fromSourceMap(map)

Transform a SourceMapConsumer into a SourceMapGenerator.

const smc = new SourceMapConsumer();
const smg = SourceMapGenerator.fromSourceMap(smc);

SourceMapGenerator.prototype.applySourceMap(sourceMapConsumer[, sourceFile[, sourceMapPath]])

This method is not implemented yet

SourceMapGenerator.prototype.addMapping(mapping)

const smg = new SourceMapGenerator();
smg.addMapping({
  generated: { line: 1, column: 0 },
  source: 'input.js',
  original: { line: 1, column: 0 },
  name: 'foo',
});

SourceMapGenerator.prototype.setSourceContent(sourceFile, sourceContent)

const smg = new SourceMapGenerator();
smg.setSourceContent('input.js', 'foobar');

SourceMapGenerator.prototype.toJSON()

const smg = new SourceMapGenerator();
smg.toJSON(); // { version: 3, names: [], sources: [], mappings: '' }

SourceMapGenerator.prototype.toString()

const smg = new SourceMapGenerator();
smg.toJSON(); // "{version:3,names:[],sources:[],mappings:''}"

SourceMapGenerator.prototype.toDecodedMap()

const smg = new SourceMapGenerator();
smg.toDecodedMap(); // { version: 3, names: [], sources: [], mappings: [] }

Known differences with other implementations

This implementation has some differences with source-map and source-map-js.

• SourceMapConsumer.prototype.eachMapping()
  • Does not support the order argument
• SourceMapGenerator.prototype.applySourceMap()
  • Not implemented