3 [![Build Status](https://travis-ci.org/mozilla/source-map.png?branch=master)](https://travis-ci.org/mozilla/source-map)
5 [![NPM](https://nodei.co/npm/source-map.png?downloads=true&downloadRank=true)](https://www.npmjs.com/package/source-map)
7 This is a library to generate and consume the source map format
8 [described here][format].
10 [format]: https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit
14 $ npm install source-map
18 <script src="https://raw.githubusercontent.com/mozilla/source-map/master/dist/source-map.min.js" defer></script>
20 --------------------------------------------------------------------------------
22 <!-- `npm run toc` to regenerate the Table of Contents -->
24 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
25 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
28 - [Examples](#examples)
29 - [Consuming a source map](#consuming-a-source-map)
30 - [Generating a source map](#generating-a-source-map)
31 - [With SourceNode (high level API)](#with-sourcenode-high-level-api)
32 - [With SourceMapGenerator (low level API)](#with-sourcemapgenerator-low-level-api)
34 - [SourceMapConsumer](#sourcemapconsumer)
35 - [new SourceMapConsumer(rawSourceMap)](#new-sourcemapconsumerrawsourcemap)
36 - [SourceMapConsumer.prototype.computeColumnSpans()](#sourcemapconsumerprototypecomputecolumnspans)
37 - [SourceMapConsumer.prototype.originalPositionFor(generatedPosition)](#sourcemapconsumerprototypeoriginalpositionforgeneratedposition)
38 - [SourceMapConsumer.prototype.generatedPositionFor(originalPosition)](#sourcemapconsumerprototypegeneratedpositionfororiginalposition)
39 - [SourceMapConsumer.prototype.allGeneratedPositionsFor(originalPosition)](#sourcemapconsumerprototypeallgeneratedpositionsfororiginalposition)
40 - [SourceMapConsumer.prototype.hasContentsOfAllSources()](#sourcemapconsumerprototypehascontentsofallsources)
41 - [SourceMapConsumer.prototype.sourceContentFor(source[, returnNullOnMissing])](#sourcemapconsumerprototypesourcecontentforsource-returnnullonmissing)
42 - [SourceMapConsumer.prototype.eachMapping(callback, context, order)](#sourcemapconsumerprototypeeachmappingcallback-context-order)
43 - [SourceMapGenerator](#sourcemapgenerator)
44 - [new SourceMapGenerator([startOfSourceMap])](#new-sourcemapgeneratorstartofsourcemap)
45 - [SourceMapGenerator.fromSourceMap(sourceMapConsumer)](#sourcemapgeneratorfromsourcemapsourcemapconsumer)
46 - [SourceMapGenerator.prototype.addMapping(mapping)](#sourcemapgeneratorprototypeaddmappingmapping)
47 - [SourceMapGenerator.prototype.setSourceContent(sourceFile, sourceContent)](#sourcemapgeneratorprototypesetsourcecontentsourcefile-sourcecontent)
48 - [SourceMapGenerator.prototype.applySourceMap(sourceMapConsumer[, sourceFile[, sourceMapPath]])](#sourcemapgeneratorprototypeapplysourcemapsourcemapconsumer-sourcefile-sourcemappath)
49 - [SourceMapGenerator.prototype.toString()](#sourcemapgeneratorprototypetostring)
50 - [SourceNode](#sourcenode)
51 - [new SourceNode([line, column, source[, chunk[, name]]])](#new-sourcenodeline-column-source-chunk-name)
52 - [SourceNode.fromStringWithSourceMap(code, sourceMapConsumer[, relativePath])](#sourcenodefromstringwithsourcemapcode-sourcemapconsumer-relativepath)
53 - [SourceNode.prototype.add(chunk)](#sourcenodeprototypeaddchunk)
54 - [SourceNode.prototype.prepend(chunk)](#sourcenodeprototypeprependchunk)
55 - [SourceNode.prototype.setSourceContent(sourceFile, sourceContent)](#sourcenodeprototypesetsourcecontentsourcefile-sourcecontent)
56 - [SourceNode.prototype.walk(fn)](#sourcenodeprototypewalkfn)
57 - [SourceNode.prototype.walkSourceContents(fn)](#sourcenodeprototypewalksourcecontentsfn)
58 - [SourceNode.prototype.join(sep)](#sourcenodeprototypejoinsep)
59 - [SourceNode.prototype.replaceRight(pattern, replacement)](#sourcenodeprototypereplacerightpattern-replacement)
60 - [SourceNode.prototype.toString()](#sourcenodeprototypetostring)
61 - [SourceNode.prototype.toStringWithSourceMap([startOfSourceMap])](#sourcenodeprototypetostringwithsourcemapstartofsourcemap)
63 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
67 ### Consuming a source map
73 names: ['bar', 'baz', 'n'],
74 sources: ['one.js', 'two.js'],
75 sourceRoot: 'http://example.com/www/js/',
76 mappings: 'CAAC,IAAI,IAAM,SAAUA,GAClB,OAAOC,IAAID;CCDb,IAAI,IAAM,SAAUE,GAClB,OAAOA'
79 var smc = new SourceMapConsumer(rawSourceMap);
81 console.log(smc.sources);
82 // [ 'http://example.com/www/js/one.js',
83 // 'http://example.com/www/js/two.js' ]
85 console.log(smc.originalPositionFor({
89 // { source: 'http://example.com/www/js/two.js',
94 console.log(smc.generatedPositionFor({
95 source: 'http://example.com/www/js/two.js',
99 // { line: 2, column: 28 }
101 smc.eachMapping(function (m) {
106 ### Generating a source map
109 [**Compiling to JavaScript, and Debugging with Source Maps**](https://hacks.mozilla.org/2013/05/compiling-to-javascript-and-debugging-with-source-maps/)
111 #### With SourceNode (high level API)
114 function compile(ast) {
116 case 'BinaryExpression':
117 return new SourceNode(
121 [compile(ast.left), " + ", compile(ast.right)]
124 return new SourceNode(
132 throw new Error("Bad AST");
136 var ast = parse("40 + 2", "add.js");
137 console.log(compile(ast).toStringWithSourceMap({
141 // map: [object SourceMapGenerator] }
144 #### With SourceMapGenerator (low level API)
147 var map = new SourceMapGenerator({
148 file: "source-mapped.js"
164 console.log(map.toString());
165 // '{"version":3,"file":"source-mapped.js","sources":["foo.js"],"names":["christopher"],"mappings":";;;;;;;;;mCAgCEA"}'
170 Get a reference to the module:
174 var sourceMap = require('source-map');
177 var sourceMap = window.sourceMap;
180 const sourceMap = require("devtools/toolkit/sourcemap/source-map.js");
183 ### SourceMapConsumer
185 A SourceMapConsumer instance represents a parsed source map which we can query
186 for information about the original file positions by giving it a file position
187 in the generated source.
189 #### new SourceMapConsumer(rawSourceMap)
191 The only parameter is the raw source map (either as a string which can be
192 `JSON.parse`'d, or an object). According to the spec, source maps have the
193 following attributes:
195 * `version`: Which version of the source map spec this map is following.
197 * `sources`: An array of URLs to the original source files.
199 * `names`: An array of identifiers which can be referenced by individual
202 * `sourceRoot`: Optional. The URL root from which all sources are relative.
204 * `sourcesContent`: Optional. An array of contents of the original source files.
206 * `mappings`: A string of base64 VLQs which contain the actual mappings.
208 * `file`: Optional. The generated filename this source map is associated with.
211 var consumer = new sourceMap.SourceMapConsumer(rawSourceMapJsonData);
214 #### SourceMapConsumer.prototype.computeColumnSpans()
216 Compute the last column for each generated mapping. The last column is
221 consumer.allGeneratedPositionsFor({ line: 2, source: "foo.coffee" })
229 consumer.computeColumnSpans();
232 consumer.allGeneratedPositionsFor({ line: 2, source: "foo.coffee" })
241 // lastColumn: Infinity } ]
245 #### SourceMapConsumer.prototype.originalPositionFor(generatedPosition)
247 Returns the original source, line, and column information for the generated
248 source's line and column positions provided. The only argument is an object with
249 the following properties:
251 * `line`: The line number in the generated source.
253 * `column`: The column number in the generated source.
255 * `bias`: Either `SourceMapConsumer.GREATEST_LOWER_BOUND` or
256 `SourceMapConsumer.LEAST_UPPER_BOUND`. Specifies whether to return the closest
257 element that is smaller than or greater than the one we are searching for,
258 respectively, if the exact element cannot be found. Defaults to
259 `SourceMapConsumer.GREATEST_LOWER_BOUND`.
261 and an object is returned with the following properties:
263 * `source`: The original source file, or null if this information is not
266 * `line`: The line number in the original source, or null if this information is
269 * `column`: The column number in the original source, or null if this
270 information is not available.
272 * `name`: The original identifier, or null if this information is not available.
275 consumer.originalPositionFor({ line: 2, column: 10 })
276 // { source: 'foo.coffee',
281 consumer.originalPositionFor({ line: 99999999999999999, column: 999999999999999 })
288 #### SourceMapConsumer.prototype.generatedPositionFor(originalPosition)
290 Returns the generated line and column information for the original source,
291 line, and column positions provided. The only argument is an object with
292 the following properties:
294 * `source`: The filename of the original source.
296 * `line`: The line number in the original source.
298 * `column`: The column number in the original source.
300 and an object is returned with the following properties:
302 * `line`: The line number in the generated source, or null.
304 * `column`: The column number in the generated source, or null.
307 consumer.generatedPositionFor({ source: "example.js", line: 2, column: 10 })
312 #### SourceMapConsumer.prototype.allGeneratedPositionsFor(originalPosition)
314 Returns all generated line and column information for the original source, line,
315 and column provided. If no column is provided, returns all mappings
316 corresponding to a either the line we are searching for or the next closest line
317 that has any mappings. Otherwise, returns all mappings corresponding to the
318 given line and either the column we are searching for or the next closest column
319 that has any offsets.
321 The only argument is an object with the following properties:
323 * `source`: The filename of the original source.
325 * `line`: The line number in the original source.
327 * `column`: Optional. The column number in the original source.
329 and an array of objects is returned, each with the following properties:
331 * `line`: The line number in the generated source, or null.
333 * `column`: The column number in the generated source, or null.
336 consumer.allGeneratedpositionsfor({ line: 2, source: "foo.coffee" })
345 #### SourceMapConsumer.prototype.hasContentsOfAllSources()
347 Return true if we have the embedded source content for every source listed in
348 the source map, false otherwise.
350 In other words, if this method returns `true`, then
351 `consumer.sourceContentFor(s)` will succeed for every source `s` in
356 if (consumer.hasContentsOfAllSources()) {
357 consumerReadyCallback(consumer);
359 fetchSources(consumer, consumerReadyCallback);
364 #### SourceMapConsumer.prototype.sourceContentFor(source[, returnNullOnMissing])
366 Returns the original source content for the source provided. The only
367 argument is the URL of the original source file.
369 If the source content for the given source is not found, then an error is
370 thrown. Optionally, pass `true` as the second param to have `null` returned
375 // [ "my-cool-lib.clj" ]
377 consumer.sourceContentFor("my-cool-lib.clj")
380 consumer.sourceContentFor("this is not in the source map");
381 // Error: "this is not in the source map" is not in the source map
383 consumer.sourceContentFor("this is not in the source map", true);
387 #### SourceMapConsumer.prototype.eachMapping(callback, context, order)
389 Iterate over each mapping between an original source/line/column and a
390 generated line/column in this source map.
392 * `callback`: The function that is called with each mapping. Mappings have the
393 form `{ source, generatedLine, generatedColumn, originalLine, originalColumn,
396 * `context`: Optional. If specified, this object will be the value of `this`
397 every time that `callback` is called.
399 * `order`: Either `SourceMapConsumer.GENERATED_ORDER` or
400 `SourceMapConsumer.ORIGINAL_ORDER`. Specifies whether you want to iterate over
401 the mappings sorted by the generated file's line/column order or the
402 original's source/line/column order, respectively. Defaults to
403 `SourceMapConsumer.GENERATED_ORDER`.
406 consumer.eachMapping(function (m) { console.log(m); })
408 // { source: 'illmatic.js',
410 // generatedColumn: 0,
412 // originalColumn: 0,
414 // { source: 'illmatic.js',
416 // generatedColumn: 0,
418 // originalColumn: 0,
422 ### SourceMapGenerator
424 An instance of the SourceMapGenerator represents a source map which is being
427 #### new SourceMapGenerator([startOfSourceMap])
429 You may pass an object with the following properties:
431 * `file`: The filename of the generated source that this source map is
434 * `sourceRoot`: A root for all relative URLs in this source map.
436 * `skipValidation`: Optional. When `true`, disables validation of mappings as
437 they are added. This can improve performance but should be used with
438 discretion, as a last resort. Even then, one should avoid using this flag when
439 running tests, if possible.
442 var generator = new sourceMap.SourceMapGenerator({
443 file: "my-generated-javascript-file.js",
444 sourceRoot: "http://example.com/app/js/"
448 #### SourceMapGenerator.fromSourceMap(sourceMapConsumer)
450 Creates a new `SourceMapGenerator` from an existing `SourceMapConsumer` instance.
452 * `sourceMapConsumer` The SourceMap.
455 var generator = sourceMap.SourceMapGenerator.fromSourceMap(consumer);
458 #### SourceMapGenerator.prototype.addMapping(mapping)
460 Add a single mapping from original source line and column to the generated
461 source's line and column for this source map being created. The mapping object
462 should have the following properties:
464 * `generated`: An object with the generated line and column positions.
466 * `original`: An object with the original line and column positions.
468 * `source`: The original source file (relative to the sourceRoot).
470 * `name`: An optional original token name for this mapping.
473 generator.addMapping({
474 source: "module-one.scm",
475 original: { line: 128, column: 0 },
476 generated: { line: 3, column: 456 }
480 #### SourceMapGenerator.prototype.setSourceContent(sourceFile, sourceContent)
482 Set the source content for an original source file.
484 * `sourceFile` the URL of the original source file.
486 * `sourceContent` the content of the source file.
489 generator.setSourceContent("module-one.scm",
490 fs.readFileSync("path/to/module-one.scm"))
493 #### SourceMapGenerator.prototype.applySourceMap(sourceMapConsumer[, sourceFile[, sourceMapPath]])
495 Applies a SourceMap for a source file to the SourceMap.
496 Each mapping to the supplied source file is rewritten using the
497 supplied SourceMap. Note: The resolution for the resulting mappings
498 is the minimum of this map and the supplied map.
500 * `sourceMapConsumer`: The SourceMap to be applied.
502 * `sourceFile`: Optional. The filename of the source file.
503 If omitted, sourceMapConsumer.file will be used, if it exists.
504 Otherwise an error will be thrown.
506 * `sourceMapPath`: Optional. The dirname of the path to the SourceMap
507 to be applied. If relative, it is relative to the SourceMap.
509 This parameter is needed when the two SourceMaps aren't in the same
510 directory, and the SourceMap to be applied contains relative source
511 paths. If so, those relative source paths need to be rewritten
512 relative to the SourceMap.
514 If omitted, it is assumed that both SourceMaps are in the same directory,
515 thus not needing any rewriting. (Supplying `'.'` has the same effect.)
517 #### SourceMapGenerator.prototype.toString()
519 Renders the source map being generated to a string.
523 // '{"version":3,"sources":["module-one.scm"],"names":[],"mappings":"...snip...","file":"my-generated-javascript-file.js","sourceRoot":"http://example.com/app/js/"}'
528 SourceNodes provide a way to abstract over interpolating and/or concatenating
529 snippets of generated JavaScript source code, while maintaining the line and
530 column information associated between those snippets and the original source
531 code. This is useful as the final intermediate representation a compiler might
532 use before outputting the generated JS and source map.
534 #### new SourceNode([line, column, source[, chunk[, name]]])
536 * `line`: The original line number associated with this source node, or null if
537 it isn't associated with an original line.
539 * `column`: The original column number associated with this source node, or null
540 if it isn't associated with an original column.
542 * `source`: The original source's filename; null if no filename is provided.
544 * `chunk`: Optional. Is immediately passed to `SourceNode.prototype.add`, see
547 * `name`: Optional. The original identifier.
550 var node = new SourceNode(1, 2, "a.cpp", [
551 new SourceNode(3, 4, "b.cpp", "extern int status;\n"),
552 new SourceNode(5, 6, "c.cpp", "std::string* make_string(size_t n);\n"),
553 new SourceNode(7, 8, "d.cpp", "int main(int argc, char** argv) {}\n"),
557 #### SourceNode.fromStringWithSourceMap(code, sourceMapConsumer[, relativePath])
559 Creates a SourceNode from generated code and a SourceMapConsumer.
561 * `code`: The generated code
563 * `sourceMapConsumer` The SourceMap for the generated code
565 * `relativePath` The optional path that relative sources in `sourceMapConsumer`
566 should be relative to.
569 var consumer = new SourceMapConsumer(fs.readFileSync("path/to/my-file.js.map", "utf8"));
570 var node = SourceNode.fromStringWithSourceMap(fs.readFileSync("path/to/my-file.js"),
574 #### SourceNode.prototype.add(chunk)
576 Add a chunk of generated JS to this source node.
578 * `chunk`: A string snippet of generated JS code, another instance of
579 `SourceNode`, or an array where each member is one of those things.
584 node.add([leftHandOperandNode, " + ", rightHandOperandNode]);
587 #### SourceNode.prototype.prepend(chunk)
589 Prepend a chunk of generated JS to this source node.
591 * `chunk`: A string snippet of generated JS code, another instance of
592 `SourceNode`, or an array where each member is one of those things.
595 node.prepend("/** Build Id: f783haef86324gf **/\n\n");
598 #### SourceNode.prototype.setSourceContent(sourceFile, sourceContent)
600 Set the source content for a source file. This will be added to the
601 `SourceMap` in the `sourcesContent` field.
603 * `sourceFile`: The filename of the source file
605 * `sourceContent`: The content of the source file
608 node.setSourceContent("module-one.scm",
609 fs.readFileSync("path/to/module-one.scm"))
612 #### SourceNode.prototype.walk(fn)
614 Walk over the tree of JS snippets in this node and its children. The walking
615 function is called once for each snippet of JS and is passed that snippet and
616 the its original associated source's line/column location.
618 * `fn`: The traversal function.
621 var node = new SourceNode(1, 2, "a.js", [
622 new SourceNode(3, 4, "b.js", "uno"),
626 new SourceNode(5, 6, "c.js", "quatro")
630 node.walk(function (code, loc) { console.log("WALK:", code, loc); })
631 // WALK: uno { source: 'b.js', line: 3, column: 4, name: null }
632 // WALK: dos { source: 'a.js', line: 1, column: 2, name: null }
633 // WALK: tres { source: 'a.js', line: 1, column: 2, name: null }
634 // WALK: quatro { source: 'c.js', line: 5, column: 6, name: null }
637 #### SourceNode.prototype.walkSourceContents(fn)
639 Walk over the tree of SourceNodes. The walking function is called for each
640 source file content and is passed the filename and source content.
642 * `fn`: The traversal function.
645 var a = new SourceNode(1, 2, "a.js", "generated from a");
646 a.setSourceContent("a.js", "original a");
647 var b = new SourceNode(1, 2, "b.js", "generated from b");
648 b.setSourceContent("b.js", "original b");
649 var c = new SourceNode(1, 2, "c.js", "generated from c");
650 c.setSourceContent("c.js", "original c");
652 var node = new SourceNode(null, null, null, [a, b, c]);
653 node.walkSourceContents(function (source, contents) { console.log("WALK:", source, ":", contents); })
654 // WALK: a.js : original a
655 // WALK: b.js : original b
656 // WALK: c.js : original c
659 #### SourceNode.prototype.join(sep)
661 Like `Array.prototype.join` except for SourceNodes. Inserts the separator
662 between each of this source node's children.
664 * `sep`: The separator.
667 var lhs = new SourceNode(1, 2, "a.rs", "my_copy");
668 var operand = new SourceNode(3, 4, "a.rs", "=");
669 var rhs = new SourceNode(5, 6, "a.rs", "orig.clone()");
671 var node = new SourceNode(null, null, null, [ lhs, operand, rhs ]);
672 var joinedNode = node.join(" ");
675 #### SourceNode.prototype.replaceRight(pattern, replacement)
677 Call `String.prototype.replace` on the very right-most source snippet. Useful
678 for trimming white space from the end of a source node, etc.
680 * `pattern`: The pattern to replace.
682 * `replacement`: The thing to replace the pattern with.
685 // Trim trailing white space.
686 node.replaceRight(/\s*$/, "");
689 #### SourceNode.prototype.toString()
691 Return the string representation of this source node. Walks over the tree and
692 concatenates all the various snippets together to one string.
695 var node = new SourceNode(1, 2, "a.js", [
696 new SourceNode(3, 4, "b.js", "uno"),
700 new SourceNode(5, 6, "c.js", "quatro")
705 // 'unodostresquatro'
708 #### SourceNode.prototype.toStringWithSourceMap([startOfSourceMap])
710 Returns the string representation of this tree of source nodes, plus a
711 SourceMapGenerator which contains all the mappings between the generated and
714 The arguments are the same as those to `new SourceMapGenerator`.
717 var node = new SourceNode(1, 2, "a.js", [
718 new SourceNode(3, 4, "b.js", "uno"),
722 new SourceNode(5, 6, "c.js", "quatro")
726 node.toStringWithSourceMap({ file: "my-output-file.js" })
727 // { code: 'unodostresquatro',
728 // map: [object SourceMapGenerator] }