@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.prototype.originalPositionFor(generatedPosition)

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

SourceMapGenerator

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

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.toDecodedMap()

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