convert-source-map

What is convert-source-map?

The convert-source-map npm package is used for dealing with inline and external source maps. It provides functionalities to convert source maps between different formats, such as from a JSON object to a base64-encoded string or from a base64-encoded string to a JSON object. It can also add and remove source map comments from files or code strings.

What are convert-source-map's main functionalities?

Convert source map from JSON to base64

This feature allows you to convert a source map from a JSON object to a base64-encoded string, which can be appended to a file as an inline source map.

const convert = require('convert-source-map');
const sourceMap = { version: 3, file: 'out.js', sources: ['foo.js', 'bar.js'], names: [], mappings: 'AAgBC' };
const base64Map = convert.fromObject(sourceMap).toBase64();

Convert source map from base64 to JSON

This feature allows you to convert a base64-encoded source map string back into a JSON object for further manipulation or analysis.

const convert = require('convert-source-map');
const base64Map = 'eyJ2ZXJzaW9uIjozLCJmaWxlIjoib3V0LmpzIiwic291cmNlcyI6WyJmb28uanMiLCJiYXIuanMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBZ0JDIn0=';
const sourceMap = convert.fromBase64(base64Map).toObject();

Add source map comment to code

This feature enables you to append a source map comment to a string of code, which can be useful when generating code dynamically.

const convert = require('convert-source-map');
const code = 'function foo() {}';
const sourceMap = convert.fromObject({ version: 3, sources: ['foo.js'], names: [], mappings: 'AAAA' });
const codeWithSourceMap = code + '\n' + sourceMap.toComment();

Remove source map comment from code

This feature allows you to remove source map comments from a string of code, which can be useful when you need to process the code further without the source map.

const convert = require('convert-source-map');
const codeWithSourceMap = 'function foo() {}\n//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbImZvby5qcyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSJ9';
const codeWithoutSourceMap = convert.removeComments(codeWithSourceMap);

Other packages similar to convert-source-map

source-map

The 'source-map' package provides functionalities to generate and consume source maps. It allows for more complex manipulation of source maps compared to 'convert-source-map', such as applying mappings from one source map to another.

source-map-support

The 'source-map-support' package adds source map support to stack traces in node.js. It is more focused on using source maps to improve debugging rather than converting or manipulating source maps.

sourcemap-codec

The 'sourcemap-codec' package is a library for encoding and decoding the mappings field of source maps. It is more specialized and lower-level compared to 'convert-source-map', focusing solely on the mappings aspect of source maps.

README

convert-source-map

Converts a source-map from/to different formats and allows adding/changing properties.

var convert = require('convert-source-map');

var json = convert
  .fromComment('//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZm9vLmpzIiwic291cmNlcyI6WyJjb25zb2xlLmxvZyhcImhpXCIpOyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSIsInNvdXJjZVJvb3QiOiIvIn0=')
  .toJSON();

var modified = convert
  .fromComment('//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZm9vLmpzIiwic291cmNlcyI6WyJjb25zb2xlLmxvZyhcImhpXCIpOyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSIsInNvdXJjZVJvb3QiOiIvIn0=')
  .setProperty('sources', [ 'CONSOLE.LOG("HI");' ])
  .toJSON();

console.log(json);
console.log(modified);

{"version":3,"file":"foo.js","sources":["console.log(\"hi\");"],"names":[],"mappings":"AAAA","sourceRoot":"/"}
{"version":3,"file":"foo.js","sources":["CONSOLE.LOG(\"HI\");"],"names":[],"mappings":"AAAA","sourceRoot":"/"}

API

fromObject(obj)

Returns source map converter from given object.

fromJSON(json)

Returns source map converter from given json string.

fromBase64(base64)

Returns source map converter from given base64 encoded json string.

fromComment(comment)

Returns source map converter from given base64 encoded json string prefixed with //# sourceMappingURL=....

fromMapFileComment(comment, mapFileDir)

Returns source map converter from given filename by parsing //# sourceMappingURL=filename.

filename must point to a file that is found inside the mapFileDir. Most tools store this file right next to the generated file, i.e. the one containing the source map.

fromSource(source[, largeSource])

Finds last sourcemap comment in file and returns source map converter or returns null if no source map comment was found.

If largeSource is set to true, an algorithm that does not use regex is applied to find the source map. This is faster and especially useful if you're running into "call stack size exceeded" errors with the default algorithm.

However, it is less accurate and may match content that isn't a source map comment.

fromMapFileSource(source, mapFileDir)

Finds last sourcemap comment in file and returns source map converter or returns null if no source map comment was found.

The sourcemap will be read from the map file found by parsing # sourceMappingURL=file comment. For more info see fromMapFileComment.

toObject()

Returns a copy of the underlying source map.

toJSON([space])

Converts source map to json string. If space is given (optional), this will be passed to JSON.stringify when the JSON string is generated.

toBase64()

Converts source map to base64 encoded json string.

toComment([options])

Converts source map to an inline comment that can be appended to the source-file.

By default, the comment is formatted like: //# sourceMappingURL=..., which you would normally see in a JS source file.

When options.multiline == true, the comment is formatted like: /*# sourceMappingURL=... */, which you would find in a CSS source file.

addProperty(key, value)

Adds given property to the source map. Throws an error if property already exists.

setProperty(key, value)

Sets given property to the source map. If property doesn't exist it is added, otherwise its value is updated.

getProperty(key)

Gets given property of the source map.

removeComments(src)

Returns src with all source map comments removed

removeMapFileComments(src)

Returns src with all source map comments pointing to map files removed.

commentRegex

Returns the regex used to find source map comments.

mapFileCommentRegex

Returns the regex used to find source map comments pointing to map files.

generateMapFileComment(file, [options])

Returns a comment that links to an external source map via file.

By default, the comment is formatted like: //# sourceMappingURL=..., which you would normally see in a JS source file.

When options.multiline == true, the comment is formatted like: /*# sourceMappingURL=... */, which you would find in a CSS source file.