sl-convert-source-map

Fork of convert-source-map with improved sourcemap parsing.

Improvements

- Better handling of malformed sourcemap comments
- More robust base64 extraction
- Improved error handling for invalid sourcemaps

License

MIT, see LICENSE file.

Original work Copyright (c) 2013 Thorsten Lorenz
Modified work Copyright (c) 2024 Sealights

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

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

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

var modified = convert
.fromComment('//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYnVpbGQvZm9vLm1pbi5qcyIsInNvdXJjZXMiOlsic3JjL2Zvby5qcyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSIsInNvdXJjZVJvb3QiOiIvIn0=')
.setProperty('sources', [ 'SRC/FOO.JS' ])
.toJSON();

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

`json
{"version":3,"file":"build/foo.min.js","sources":["src/foo.js"],"names":[],"mappings":"AAAA","sourceRoot":"/"}
{"version":3,"file":"build/foo.min.js","sources":["SRC/FOO.JS"],"names":[],"mappings":"AAAA","sourceRoot":"/"}
`

Upgrading

Prior to v2.0.0, the fromMapFileComment and fromMapFileSource functions took a String directory path and used that to resolve & read the source map file from the filesystem. However, this made the library limited to nodejs environments and broke on sources with querystrings.

In v2.0.0, you now need to pass a function that does the file reading. It will receive the source filename as a String that you can resolve to a filesystem path, URL, or anything else.

If you are using convert-source-map in nodejs and want the previous behavior, you'll use a function like such:

`diff
+ var fs = require('fs'); // Import the fs module to read a file
+ var path = require('path'); // Import the path module to resolve a path against your directory
- var conv = convert.fromMapFileSource(css, '../my-dir');
+ var conv = convert.fromMapFileSource(css, function (filename) {
+ return fs.readFileSync(path.resolve('../my-dir', filename), 'utf-8');
+ });
`

API

$3

Returns source map converter from given object.

$3

Returns source map converter from given json string.

$3

Returns source map converter from given uri encoded json string.

$3

Returns source map converter from given base64 encoded json string.

$3

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

$3

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

readMap must be a function which receives the source map filename and returns either a String or Buffer of the source map (if read synchronously), or a Promise containing a String or Buffer of the source map (if read asynchronously).

If readMap doesn't return a Promise, fromMapFileComment will return a source map converter synchronously.

If readMap returns a Promise, fromMapFileComment will also return Promise. The Promise will be either resolved with the source map converter or rejected with an error.

#### Examples

Synchronous read in Node.js:

`js
var convert = require('convert-source-map');
var fs = require('fs');

function readMap(filename) {
return fs.readFileSync(filename, 'utf8');
}

var json = convert
.fromMapFileComment('//# sourceMappingURL=map-file-comment.css.map', readMap)
.toJSON();
console.log(json);
`


Asynchronous read in Node.js:

`js
var convert = require('convert-source-map');
var { promises: fs } = require('fs'); // Notice the promises import

function readMap(filename) {
return fs.readFile(filename, 'utf8');
}

var converter = await convert.fromMapFileComment('//# sourceMappingURL=map-file-comment.css.map', readMap)
var json = converter.toJSON();
console.log(json);
`

Asynchronous read in the browser:

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

async function readMap(url) {
const res = await fetch(url);
return res.text();
}

const converter = await convert.fromMapFileComment('//# sourceMappingURL=map-file-comment.css.map', readMap)
var json = converter.toJSON();
console.log(json);
`

$3

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

$3

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

readMap must be a function which receives the source map filename and returns either a String or Buffer of the source map (if read synchronously), or a Promise containing a String or Buffer of the source map (if read asynchronously).

If readMap doesn't return a Promise, fromMapFileSource will return a source map converter synchronously.

If readMap returns a Promise, fromMapFileSource will also return Promise. The Promise will be either resolved with the source map converter or rejected with an error.

$3

Returns a copy of the underlying source map.

$3

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

$3

Converts source map to uri encoded json string.

$3

Converts source map to base64 encoded json string.

$3

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.encoding == 'uri', the data will be uri encoded, otherwise they will be base64 encoded.

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

$3

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

$3

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

$3

Gets given property of the source map.

$3

Returns src with all source map comments removed

$3

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

$3

Provides __a fresh__ RegExp each time it is accessed. Can be used to find source map comments.

Breaks down a source map comment into groups: Groups: 1: media type, 2: MIME type, 3: charset, 4: encoding, 5: data.

$3

Provides __a fresh__ RegExp each time it is accessed. Can be used to find source map comments pointing to map files.

$3

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.

[ci-url]: https://github.com/thlorenz/convert-source-map/actions?query=workflow:ci
[ci-image]: https://img.shields.io/github/actions/workflow/status/thlorenz/convert-source-map/ci.yml?branch=master&style=flat-square