Source Map

This is a library to generate and consume the source map format described here.

Use with Node

$ npm install source-map

Use on the Web

<script src="https://unpkg.com/source-map@0.7.3/dist/source-map.js"></script>
<script>
    sourceMap.SourceMapConsumer.initialize({
        "lib/mappings.wasm": "https://unpkg.com/source-map@0.7.3/lib/mappings.wasm"
    });
</script>

Table of Contents

• Examples
  • Consuming a source map
  • Generating a source map
    • With SourceNode (high level API)
    • With SourceMapGenerator (low level API)
• API
  • SourceMapConsumer
    • SourceMapConsumer.initialize(options)
    • new SourceMapConsumer(rawSourceMap)
    • SourceMapConsumer.with
    • SourceMapConsumer.prototype.destroy()
    • SourceMapConsumer.prototype.computeColumnSpans()
    • SourceMapConsumer.prototype.originalPositionFor(generatedPosition)
    • SourceMapConsumer.prototype.generatedPositionFor(originalPosition)
    • SourceMapConsumer.prototype.allGeneratedPositionsFor(originalPosition)
    • SourceMapConsumer.prototype.hasContentsOfAllSources()
    • SourceMapConsumer.prototype.sourceContentFor(source[, returnNullOnMissing])
    • SourceMapConsumer.prototype.eachMapping(callback, context, order)
  • SourceMapGenerator
    • new SourceMapGenerator([startOfSourceMap])
    • SourceMapGenerator.fromSourceMap(sourceMapConsumer)
    • SourceMapGenerator.prototype.addMapping(mapping)
    • SourceMapGenerator.prototype.setSourceContent(sourceFile, sourceContent)
    • [SourceMapGenerator.prototype.applySourceMap(sourceMapConsumer[, sourceFile[, sourceMapPath]])](#sourcemapgeneratorprototypeapplysourcemapsourcemapconsumer-sourcefile-sourcemappath)
    • SourceMapGenerator.prototype.toString()
  • SourceNode
    • [new SourceNode([line, column, source[, chunk[, name]]])](#new-sourcenodeline-column-source-chunk-name)
    • SourceNode.fromStringWithSourceMap(code, sourceMapConsumer[, relativePath])
    • SourceNode.prototype.add(chunk)
    • SourceNode.prototype.prepend(chunk)
    • SourceNode.prototype.setSourceContent(sourceFile, sourceContent)
    • SourceNode.prototype.walk(fn)
    • SourceNode.prototype.walkSourceContents(fn)
    • SourceNode.prototype.join(sep)
    • SourceNode.prototype.replaceRight(pattern, replacement)
    • SourceNode.prototype.toString()
    • SourceNode.prototype.toStringWithSourceMap([startOfSourceMap])

Examples

Consuming a source map

const rawSourceMap = {
  version: 3,
  file: 'min.js',
  names: ['bar', 'baz', 'n'],
  sources: ['one.js', 'two.js'],
  sourceRoot: 'http://example.com/www/js/',
  mappings: 'CAAC,IAAI,IAAM,SAAUA,GAClB,OAAOC,IAAID;CCDb,IAAI,IAAM,SAAUE,GAClB,OAAOA'
};

const whatever = await SourceMapConsumer.with(rawSourceMap, null, consumer => {

  console.log(consumer.sources);
  // [ 'http://example.com/www/js/one.js',
  //   'http://example.com/www/js/two.js' ]

  console.log(consumer.originalPositionFor({
    line: 2,
    column: 28
  }));
  // { source: 'http://example.com/www/js/two.js',
  //   line: 2,
  //   column: 10,
  //   name: 'n' }

  console.log(consumer.generatedPositionFor({
    source: 'http://example.com/www/js/two.js',
    line: 2,
    column: 10
  }));
  // { line: 2, column: 28 }

  consumer.eachMapping(function (m) {
    // ...
  });

  return computeWhatever();
});

Generating a source map

In depth guide: Compiling to JavaScript, and Debugging with Source Maps

With SourceNode (high level API)

function compile(ast) {
  switch (ast.type) {
  case 'BinaryExpression':
    return new SourceNode(
      ast.location.line,
      ast.location.column,
      ast.location.source,
      [compile(ast.left), " + ", compile(ast.right)]
    );
  case 'Literal':
    return new SourceNode(
      ast.location.line,
      ast.location.column,
      ast.location.source,
      String(ast.value)
    );
  // ...
  default:
    throw new Error("Bad AST");
  }
}

var ast = parse("40 + 2", "add.js");
console.log(compile(ast).toStringWithSourceMap({
  file: 'add.js'
}));
// { code: '40 + 2',
//   map: [object SourceMapGenerator] }

With SourceMapGenerator (low level API)

var map = new SourceMapGenerator({
  file: "source-mapped.js"
});

map.addMapping({
  generated: {
    line: 10,
    column: 35
  },
  source: "foo.js",
  original: {
    line: 33,
    column: 2
  },
  name: "christopher"
});

console.log(map.toString());
// '{"version":3,"file":"source-mapped.js","sources":["foo.js"],"names":["christopher"],"mappings":";;;;;;;;;mCAgCEA"}'

API

Get a reference to the module:

// Node.js
var sourceMap = require('source-map');

// Browser builds
var sourceMap = window.sourceMap;

// Inside Firefox
const sourceMap = require("devtools/toolkit/sourcemap/source-map.js");

SourceMapConsumer

A SourceMapConsumer instance represents a parsed source map which we can query for information about the original file positions by giving it a file position in the generated source.

SourceMapConsumer.initialize(options)

When using SourceMapConsumer outside of node.js, for example on the Web, it needs to know from what URL to load lib/mappings.wasm. You must inform it by calling initialize before constructing any SourceMapConsumers.

The options object has the following properties:

• "lib/mappings.wasm": A String containing the URL of the lib/mappings.wasm file, or an ArrayBuffer with the contents of lib/mappings.wasm.

```js sourceMap.SourceMapConsumer.initializ