The @jridgewell/trace-mapping package is designed to work with source maps, which are files that provide a mapping between the transformed, bundled, or minified code and the original source files. This package allows users to trace the source location of a piece of code through a source map, which is particularly useful for debugging purposes when working with compiled or minified JavaScript.

What are @jridgewell/trace-mapping's main functionalities?

Trace Source Location

This feature allows you to trace the original source location of a specific line and column in the transformed file. You can use the source map to find out where in the original source code a piece of the transformed code came from.

{"version":3,"file":"min.js","names":["bar","baz","n"],"sources":["one.js","two.js"],"sourceRoot":"http://example.com/www/js/","mappings":"CAAC,IAAI,IAAM,SAAUA,GAClB,OAAOC,MAAM,K"}

Generate Source Map

This feature allows you to generate a new source map by adding mappings between the original and the transformed code. This is useful when you are creating a new tool that transforms code and you want to provide source maps for debugging.

const { SourceMapGenerator } = require('@jridgewell/trace-mapping');
const generator = new SourceMapGenerator({ file: 'min.js' });
generator.addMapping({
  generated: { line: 1, column: 0 },
  source: 'one.js',
  original: { line: 1, column: 0 }
});
const map = generator.toJSON();

Other packages similar to @jridgewell/trace-mapping

Readme

Source

@jridgewell/trace-mapping

Trace the original position through a source map

trace-mapping allows you to take the line and column of an output file and trace it to the original location in the source file through a source map.

You may already be familiar with the source-map package's SourceMapConsumer. This provides the same originalPositionFor API, without requires WASM.

Installation

npm install @jridgewell/trace-mapping

Usage

import { TraceMap, originalPositionFor } from '@jridgewell/trace-mapping';

const tracer = new TraceMap({
  version: 3,
  sources: ['input.js'],
  names: ['foo'],
  mappings: 'KAyCIA',
});

// Lines start at line 1, columns at column 0.
const traced = originalPositionFor(tracer, { line: 1, column: 5 });
assert.deepEqual(traced, {
  source: 'input.js',
  line: 42,
  column: 4,
  name: 'foo',
});

We also provide a lower level API to get the actual segment that matches our line and column. Unlike originalPositionFor, traceSegment uses a 0-base for line:

import { originalPositionFor } from '@jridgewell/trace-mapping';

// line is 0-base.
const traced = traceSegment(tracer, /* line */ 0, /* column */ 5);

// Segments are [outputColumn, sourcesIndex, sourceLine, sourceColumn, namesIndex]
// Again, line is 0-base and so is sourceLine
assert.deepEqual(traced, [5, 0, 41, 4, 0]);

Benchmarks

trace-mapping is the fastest source map tracing library, by a factor of 4-10x when constructing/parsing source maps and another 6-10x when using originalPositionFor on an already constructed instance.

node v16.13.2

trace-mapping: decoded JSON input x 7,224 ops/sec ±0.24% (99 runs sampled)
trace-mapping: encoded JSON input x 22,539 ops/sec ±0.17% (98 runs sampled)
trace-mapping: decoded Object input x 161,786 ops/sec ±0.11% (101 runs sampled)
trace-mapping: encoded Object input x 24,485 ops/sec ±0.10% (100 runs sampled)
source-map-js: encoded Object input x 6,195 ops/sec ±0.36% (100 runs sampled)
source-map:    encoded Object input x 2,602 ops/sec ±0.16% (100 runs sampled)
Fastest is trace-mapping: decoded Object input

trace-mapping: decoded originalPositionFor x 19,860 ops/sec ±0.11% (101 runs sampled)
trace-mapping: encoded originalPositionFor x 19,250 ops/sec ±0.23% (100 runs sampled)
source-map-js: encoded originalPositionFor x 2,897 ops/sec ±0.09% (100 runs sampled)
source-map:    encoded originalPositionFor x 1,571 ops/sec ±0.10% (100 runs sampled)
Fastest is trace-mapping: decoded originalPositionFor

Keywords

FAQs

What is @jridgewell/trace-mapping?

Is @jridgewell/trace-mapping popular?

Is @jridgewell/trace-mapping well maintained?

Last updated on 09 Feb 2022

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install