source-list-map

What is source-list-map?

The source-list-map npm package is a utility designed to manage source maps and source content. It allows for efficient manipulation of source maps and the integration of different pieces of source content, making it a valuable tool for developers working with complex JavaScript projects where tracking and combining source maps is necessary.

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

Add a source to the map

This feature allows you to add a new source, including its code, filename, and original source code, to the source list map. It's useful for building a source map from scratch or adding new sources to an existing map.

var SourceListMap = require('source-list-map').SourceListMap;
var map = new SourceListMap();
map.add('source code', 'source-file.js', 'source code');

Generate source map

After adding sources to the source list map, you can generate a source map. This feature outputs the source map as a string, which can be used in a JavaScript file or saved as a separate source map file. It's essential for debugging purposes, allowing you to trace back minified code to its original source.

var map = new SourceListMap();
map.add('source code', 'source-file.js', 'source code');
var sourceMap = map.toStringWithSourceMap({file: 'output-file.js'});

Combine source maps

This feature demonstrates how to combine two source maps into one. It's particularly useful when you're working with multiple JavaScript files or libraries and need to create a single source map that references all the original source files.

var SourceListMap = require('source-list-map').SourceListMap;
var map1 = new SourceListMap();
var map2 = new SourceListMap();
map1.add('source code 1', 'source-file1.js', 'source code 1');
map2.add('source code 2', 'source-file2.js', 'source code 2');
map1.add(map2);
var combinedMap = map1.toStringWithSourceMap({file: 'combined-output.js'});

Other packages similar to source-list-map

source-map

The 'source-map' package provides functionalities for generating and consuming source maps. It allows for the creation, manipulation, and querying of source maps, similar to 'source-list-map'. However, 'source-map' offers a more comprehensive API for dealing with source maps, including parsing and serialization, which might make it more suitable for complex use cases.

magic-string

While 'magic-string' is primarily focused on providing utilities for editing and generating source code and its maps, it shares some functionalities with 'source-list-map', particularly in manipulating source content and generating source maps. 'magic-string' is often preferred for its performance and additional features for source code transformation and manipulation.

README

source-list-map

API

Example

var SourceListMap = require("source-list-map").SourceListMap;

// Create a new map
var map = new SourceListMap();

// Add generated code that is map line to line to some soure
map.add("Generated\ncode1\n", "source-code.js", "Orginal\nsource");

// Add generated code that isn't mapped
map.add("Generated\ncode2\n");

// Get SourceMap and generated source
map.toStringWithSourceMap({ file: "generated-code.js" });
// {
//   source: 'Generated\ncode1\nGenerated\ncode2\n',
//   map: {
//      version: 3,
//      file: 'generated-code.js',
//      sources: [ 'source-code.js' ],
//      sourcesContent: [ 'Orginal\nsource' ],
//      mappings: 'AAAA;AACA;;;'
//    }
// }

// Convert existing SourceMap into SourceListMap
// (Only the first mapping per line is preserved)
var fromStringWithSourceMap = require("source-list-map").fromStringWithSourceMap;
var map = fromStringWithSourceMap("Generated\ncode", { version: 3, ... });

new SourceListMap()

SourceListMap.prototype.add

SourceListMap.prototype.add(generatedCode: string)
SourceListMap.prototype.add(generatedCode: string, source: string, originalSource: string)
SourceListMap.prototype.add(sourceListMap: SourceListMap)

Append some stuff.

SourceListMap.prototype.prepend

SourceListMap.prototype.prepend(generatedCode: string)
SourceListMap.prototype.prepend(generatedCode: string, source: string, originalSource: string)
SourceListMap.prototype.prepend(sourceListMap: SourceListMap)

Prepend some stuff.

SourceListMap.prototype.toString()

Get generated code.

SourceListMap.prototype.toStringWithSourceMap

SourceListMap.prototype.toStringWithSourceMap(options: object)

Get generated code and SourceMap. options can contains file property which defines the file property of the SourceMap.

SourceListMap.prototype.mapGeneratedCode

SourceListMap.prototype.mapGeneratedCode(fn: function) : SourceListMap

Applies fn to each generated code block (per line). The returned value is set as new generated code. Returns a new SourceListMap.

Removing and adding lines is supported. The SourceMap complexity will increase when doing this.

Test

License

Copyright (c) 2017 JS Foundation

MIT (http://www.opensource.org/licenses/mit-license.php)