This is a library to generate and consume the source map format described here.
In depth guide: Compiling to JavaScript, and Debugging with Source Maps
Get a reference to the module:
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.
The only parameter is the raw source map (either as a string which can be JSON.parse
'd, or an object). According to the spec, source maps have the following attributes:
version
: Which version of the source map spec this map is following.
sources
: An array of URLs to the original source files.
names
: An array of identifiers which can be referenced by individual mappings.
sourceRoot
: Optional. The URL root from which all sources are relative.
sourcesContent
: Optional. An array of contents of the original source files.
mappings
: A string of base64 VLQs which contain the actual mappings.
file
: Optional. The generated filename this source map is associated with.
Compute the last column for each generated mapping. The last column is inclusive.
Returns the original source, line, and column information for the generated source's line and column positions provided. The only argument is an object with the following properties:
line
: The line number in the generated source.
column
: The column number in the generated source.
bias
: Either SourceMapConsumer.GREATEST_LOWER_BOUND
or SourceMapConsumer.LEAST_UPPER_BOUND
. Specifies whether to return the closest element that is smaller than or greater than the one we are searching for, respectively, if the exact element cannot be found. Defaults to SourceMapConsumer.GREATEST_LOWER_BOUND
.
and an object is returned with the following properties:
source
: The original source file, or null if this information is not available.
line
: The line number in the original source, or null if this information is not available.
column
: The column number in the original source, or null if this information is not available.
name
: The original identifier, or null if this information is not available.
Returns the generated line and column information for the original source, line, and column positions provided. The only argument is an object with the following properties:
source
: The filename of the original source.
line
: The line number in the original source.
column
: The column number in the original source.
and an object is returned with the following properties:
line
: The line number in the generated source, or null.
column
: The column number in the generated source, or null.
Returns all generated line and column information for the original source, line, and column provided. If no column is provided, returns all mappings corresponding to a either the line we are searching for or the next closest line that has any mappings. Otherwise, returns all mappings corresponding to the given line and either the column we are searching for or the next closest column that has any offsets.
The only argument is an object with the following properties:
source
: The filename of the original source.
line
: The line number in the original source.
column
: Optional. The column number in the original source.
and an array of objects is returned, each with the following properties:
line
: The line number in the generated source, or null.
column
: The column number in the generated source, or null.
Return true if we have the embedded source content for every source listed in the source map, false otherwise.
In other words, if this method returns true
, then consumer.sourceContentFor(s)
will succeed for every source s
in consumer.sources
.
Returns the original source content for the source provided. The only argument is the URL of the original source file.
If the source content for the given source is not found, then an error is thrown. Optionally, pass true
as the second param to have null
returned instead.
Iterate over each mapping between an original source/line/column and a generated line/column in this source map.
callback
: The function that is called with each mapping. Mappings have the form { source, generatedLine, generatedColumn, originalLine, originalColumn, name }
context
: Optional. If specified, this object will be the value of this
every time that callback
is called.
order
: Either SourceMapConsumer.GENERATED_ORDER
or SourceMapConsumer.ORIGINAL_ORDER
. Specifies whether you want to iterate over the mappings sorted by the generated file's line/column order or the original's source/line/column order, respectively. Defaults to SourceMapConsumer.GENERATED_ORDER
.
An instance of the SourceMapGenerator represents a source map which is being built incrementally.
You may pass an object with the following properties:
file
: The filename of the generated source that this source map is associated with.
sourceRoot
: A root for all relative URLs in this source map.
skipValidation
: Optional. When true
, disables validation of mappings as they are added. This can improve performance but should be used with discretion, as a last resort. Even then, one should avoid using this flag when running tests, if possible.
Creates a new SourceMapGenerator
from an existing SourceMapConsumer
instance.
sourceMapConsumer
The SourceMap.
Add a single mapping from original source line and column to the generated source's line and column for this source map being created. The mapping object should have the following properties:
generated
: An object with the generated line and column positions.
original
: An object with the original line and column positions.
source
: The original source file (relative to the sourceRoot).
name
: An optional original token name for this mapping.
Set the source content for an original source file.
sourceFile
the URL of the original source file.
sourceContent
the content of the source file.
Applies a SourceMap for a source file to the SourceMap. Each mapping to the supplied source file is rewritten using the supplied SourceMap. Note: The resolution for the resulting mappings is the minimum of this map and the supplied map.
sourceMapConsumer
: The SourceMap to be applied.
sourceFile
: Optional. The filename of the source file. If omitted, sourceMapConsumer.file will be used, if it exists. Otherwise an error will be thrown.
sourceMapPath
: Optional. The dirname of the path to the SourceMap to be applied. If relative, it is relative to the SourceMap.
This parameter is needed when the two SourceMaps aren't in the same directory, and the SourceMap to be applied contains relative source paths. If so, those relative source paths need to be rewritten relative to the SourceMap.
If omitted, it is assumed that both SourceMaps are in the same directory, thus not needing any rewriting. (Supplying '.'
has the same effect.)
Renders the source map being generated to a string.
SourceNodes provide a way to abstract over interpolating and/or concatenating snippets of generated JavaScript source code, while maintaining the line and column information associated between those snippets and the original source code. This is useful as the final intermediate representation a compiler might use before outputting the generated JS and source map.
line
: The original line number associated with this source node, or null if it isn't associated with an original line.
column
: The original column number associated with this source node, or null if it isn't associated with an original column.
source
: The original source's filename; null if no filename is provided.
chunk
: Optional. Is immediately passed to SourceNode.prototype.add
, see below.
name
: Optional. The original identifier.
Creates a SourceNode from generated code and a SourceMapConsumer.
code
: The generated code
sourceMapConsumer
The SourceMap for the generated code
relativePath
The optional path that relative sources in sourceMapConsumer
should be relative to.
Add a chunk of generated JS to this source node.
chunk
: A string snippet of generated JS code, another instance of
SourceNode
, or an array where each member is one of those things.
Prepend a chunk of generated JS to this source node.
chunk
: A string snippet of generated JS code, another instance of
SourceNode
, or an array where each member is one of those things.
Set the source content for a source file. This will be added to the SourceMap
in the sourcesContent
field.
sourceFile
: The filename of the source file
sourceContent
: The content of the source file
Walk over the tree of JS snippets in this node and its children. The walking function is called once for each snippet of JS and is passed that snippet and the its original associated source's line/column location.
fn
: The traversal function.
Walk over the tree of SourceNodes. The walking function is called for each source file content and is passed the filename and source content.
fn
: The traversal function.
Like Array.prototype.join
except for SourceNodes. Inserts the separator between each of this source node's children.
sep
: The separator.
Call String.prototype.replace
on the very right-most source snippet. Useful for trimming white space from the end of a source node, etc.
pattern
: The pattern to replace.
replacement
: The thing to replace the pattern with.
Return the string representation of this source node. Walks over the tree and concatenates all the various snippets together to one string.
Returns the string representation of this tree of source nodes, plus a SourceMapGenerator which contains all the mappings between the generated and original sources.
The arguments are the same as those to new SourceMapGenerator
.
Fix for regression when people were using numbers as names in source maps. See
236.
Fix "regression" of unsupported, implementation behavior that half the world happens to have come to depend on. See #235.
Fix regression involving function hoisting in SpiderMonkey. See #233.
Large performance improvements to source-map serialization. See #228 and #229.
Do not include unnecessary distribution files. See
commit ef7006f8d1647e0a83fdc60f04f5a7ca54886f86.
Include browser distributions of the library in package.json's files
. See
issue #212.
Fix latent bugs in IndexedSourceMapConsumer.prototype._parseMappings. See
ff05274becc9e6e1295ed60f3ea090d31d843379.
Node 0.8 is no longer supported.
Use webpack instead of dryice for bundling.
Big speedups serializing source maps. See pull request #203.
Fix a bug with SourceMapConsumer.prototype.sourceContentFor
and sources that explicitly start with the source root. See issue #199.
Fix an issue where using a SourceMapGenerator
after having created a SourceMapConsumer
from it via SourceMapConsumer.fromSourceMap
failed. See issue #191.
Fix an issue with where SourceMapGenerator
would mistakenly consider different mappings as duplicates of each other and avoid generating them. See issue #192.
A very large number of performance improvements, particularly when parsing source maps. Collectively about 75% of time shaved off of the source map parsing benchmark!
Fix a bug in SourceMapConsumer.prototype.allGeneratedPositionsFor
and fuzzy searching in the presence of a column option. See issue #177.
Fix a bug with joining a source and its source root when the source is above the root. See issue #182.
Add the SourceMapConsumer.prototype.hasContentsOfAllSources
method to determine when all sources' contents are inlined into the source map. See issue #190.
Add an .npmignore
file so that the benchmarks aren't pulled down by dependent projects. Issue #169.
Add an optional column
argument to SourceMapConsumer.prototype.allGeneratedPositionsFor
and better handle lines with no mappings. Issues #172 and #173.
Fix accidentally defining a global variable. #170.
The default direction for fuzzy searching was changed back to its original direction. See #164.
There is now a bias
option you can supply to SourceMapConsumer
to control the fuzzy searching direction. See #167.
About an 8% speed up in parsing source maps. See #159.
Added a benchmark for parsing and generating source maps.
Change the default direction that searching for positions fuzzes when there is not an exact match. See #154.
Support for environments using json2.js for JSON serialization. See #156.
Support for consuming "indexed" source maps which do not have any remote
sections. See pull request #127. This introduces a minor backwards
incompatibility if you are monkey patching SourceMapConsumer.prototype
methods.
Performance improvements for SourceMapGenerator
and SourceNode
. See issue
148 for some discussion and issues #150, #151, and #152 for implementations.
Fix an issue where SourceNode
s from different versions of the source-map
library couldn't be used in conjunction with each other. See issue #142.
Fix a bug with getting the source content of relative sources with a "./" prefix. See issue #145 and Bug 1090768.
Add the SourceMapConsumer.prototype.computeColumnSpans
method to compute the column span of each mapping.
Add the SourceMapConsumer.prototype.allGeneratedPositionsFor
method to find all generated positions associated with a given original source and line.
Performance improvements for parsing source maps in SourceMapConsumer.
Fix a bug where setting a source's contents to null before any source content
had been set before threw a TypeError. See issue #131.
Fix a bug where finding relative paths from an empty path were creating
absolute paths. See issue #129.
Fix a bug where if the source root was an empty string, relative source paths
would turn into absolute source paths. Issue #124.
Allow the names
mapping property to be an empty string. Issue #121.
A third optional parameter was added to SourceNode.fromStringWithSourceMap
to specify a path that relative sources in the second parameter should be relative to. Issue #105.
If no file property is given to a SourceMapGenerator
, then the resulting source map will no longer have a null
file property. The property will simply not exist. Issue #104.
Fixed a bug where consecutive newlines were ignored in SourceNode
s. Issue #116.
Make SourceNode
work with windows style ("\r\n") newlines. Issue #103.
Fix bug involving source contents and the SourceMapGenerator.prototype.applySourceMap
. Issue #100.
Fix some edge cases surrounding path joining and URL resolution.
Add a third parameter for relative path to SourceMapGenerator.prototype.applySourceMap
.
Fix issues with mappings and EOLs.
Fixed a bug where SourceMapConsumer couldn't handle negative relative columns (issue 92).
Fixed test runner to actually report number of failed tests as its process exit code.
Fixed a typo when reporting bad mappings (issue 87).
Delay parsing the mappings in SourceMapConsumer until queried for a source location.
Support Sass source maps (which at the time of writing deviate from the spec in small ways) in SourceMapConsumer.
Do not join source root with a source, when the source is a data URI.
Extend the test runner to allow running single specific test files at a time.
Performance improvements in SourceNode.prototype.walk
and SourceMapConsumer.prototype.eachMapping
.
Source map browser builds will now work inside Workers.
Better error messages when attempting to add an invalid mapping to a SourceMapGenerator
.
Allow duplicate entries in the names
and sources
arrays of source maps
(usually from TypeScript) we are parsing. Fixes github issue 72.
Skip duplicate mappings when creating source maps from SourceNode; github
issue 75.
Don't throw an error when the file
property is missing in SourceMapConsumer,
we don't use it anyway.
Fix SourceNode.fromStringWithSourceMap for empty maps. Fixes github issue 70.
Make compatible with browserify
Fix issue with absolute paths and file://
URIs. See
Fix issue with absolute paths and sourcesContent, github issue 64.
Ignore duplicate mappings in SourceMapGenerator. Fixes github issue 21.
Fixed handling of sources that start with a slash so that they are relative to
the source root's host.
Fixed github issue #43: absolute URLs aren't joined with the source root
anymore.
Using Travis CI to run tests.
Fixed a bug in the handling of sourceRoot.
Added SourceNode.fromStringWithSourceMap.
Added missing documentation.
Fixed the generating of empty mappings in SourceNode.
Added SourceMapGenerator.applySourceMap.
The sourceRoot is now handled consistently.
Added SourceMapGenerator.fromSourceMap.
SourceNode now generates empty mappings too.
Added name support to SourceNode.
Added sourcesContent support to the customer and generator.