@parcel/source-map

What is @parcel/source-map?

@parcel/source-map is a library for working with source maps, which are files that map from the transformed source code back to the original source code. This is useful for debugging and understanding the transformations applied to the code.

What are @parcel/source-map's main functionalities?

Creating a Source Map

This feature allows you to create a new source map and add mappings to it using VLQ (Variable Length Quantity) encoding.

const { SourceMap } = require('@parcel/source-map');
const map = new SourceMap();
map.addVLQMap({
  version: 3,
  file: 'out.js',
  sources: ['foo.js', 'bar.js'],
  names: ['src', 'maps', 'are', 'fun'],
  mappings: 'AA,AB;;ABCDE;' // VLQ encoded mappings
});
console.log(map.toBuffer());

Adding a Mapping

This feature allows you to add individual mappings to the source map, specifying the generated and original positions, the source file, and an optional name.

const { SourceMap } = require('@parcel/source-map');
const map = new SourceMap();
map.addMapping({
  generated: { line: 1, column: 5 },
  original: { line: 2, column: 10 },
  source: 'source.js',
  name: 'myFunction'
});
console.log(map.toBuffer());

Loading an Existing Source Map

This feature allows you to load an existing source map into the SourceMap object, enabling further manipulation or inspection.

const { SourceMap } = require('@parcel/source-map');
const existingMap = {
  version: 3,
  file: 'out.js',
  sources: ['foo.js', 'bar.js'],
  names: ['src', 'maps', 'are', 'fun'],
  mappings: 'AA,AB;;ABCDE;'
};
const map = new SourceMap();
map.addVLQMap(existingMap);
console.log(map.toBuffer());

Generating Source Map Buffer

This feature allows you to generate a buffer representation of the source map, which can be written to a file or used in other ways.

const { SourceMap } = require('@parcel/source-map');
const map = new SourceMap();
map.addMapping({
  generated: { line: 1, column: 5 },
  original: { line: 2, column: 10 },
  source: 'source.js',
  name: 'myFunction'
});
const buffer = map.toBuffer();
console.log(buffer);

Other packages similar to @parcel/source-map

source-map

The 'source-map' package is a library for generating and consuming source maps. It provides similar functionalities to @parcel/source-map, such as creating source maps, adding mappings, and loading existing maps. However, 'source-map' is more widely used and has a larger community.

source-map-support

The 'source-map-support' package provides source map support for stack traces in Node.js. While it does not offer the same level of manipulation capabilities as @parcel/source-map, it is useful for debugging purposes by providing better error stack traces.

convert-source-map

The 'convert-source-map' package allows you to convert source maps from/to different formats and embed/extract them from code. It complements @parcel/source-map by providing additional utilities for working with source maps in various formats.

README

Parcel's source-map library

A purpose build source-maps library for combining and manipulating source-maps.

For just reading source-maps, this library does not outperform the probably more stable and well-known package source-map by Mozilla.

Why did we write this library

Parcel is a performance concious bundler, and therefore we like to optimise Parcel's performance as much as possible.

Our original source-map implementation used mozilla's source-map and a bunch of javascript and had issues with memory usage and serialisation times (we were keeping all mappings in memory using JS objects and write/read it using JSON for caching).

This implementation has been written from scratch in C++ minimizing the memory usage, by utilising indexes for sources and names and optimising serialisation times by using flatbuffers instead of JSON for caching.

Compile flatbuffer schema

cd ./src && ../flatc --cpp ./sourcemap-schema.fbs && cd ..