| # @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`][source-map] package's `SourceMapConsumer`. This | |
| provides the same `originalPositionFor` and `generatedPositionFor` API, without requiring WASM. | |
| ## Installation | |
| ```sh | |
| npm install @jridgewell/trace-mapping | |
| ``` | |
| ## Usage | |
| ```typescript | |
| import { | |
| TraceMap, | |
| originalPositionFor, | |
| generatedPositionFor, | |
| sourceContentFor, | |
| isIgnored, | |
| } from '@jridgewell/trace-mapping'; | |
| const tracer = new TraceMap({ | |
| version: 3, | |
| sources: ['input.js'], | |
| sourcesContent: ['content of input.js'], | |
| names: ['foo'], | |
| mappings: 'KAyCIA', | |
| ignoreList: [], | |
| }); | |
| // 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', | |
| }); | |
| const content = sourceContentFor(tracer, traced.source); | |
| assert.strictEqual(content, 'content for input.js'); | |
| const generated = generatedPositionFor(tracer, { | |
| source: 'input.js', | |
| line: 42, | |
| column: 4, | |
| }); | |
| assert.deepEqual(generated, { | |
| line: 1, | |
| column: 5, | |
| }); | |
| const ignored = isIgnored(tracer, 'input.js'); | |
| assert.equal(ignored, false); | |
| ``` | |
| 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`: | |
| ```typescript | |
| import { traceSegment } 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]); | |
| ``` | |
| ### SectionedSourceMaps | |
| The sourcemap spec defines a special `sections` field that's designed to handle concatenation of | |
| output code with associated sourcemaps. This type of sourcemap is rarely used (no major build tool | |
| produces it), but if you are hand coding a concatenation you may need it. We provide an `AnyMap` | |
| helper that can receive either a regular sourcemap or a `SectionedSourceMap` and returns a | |
| `TraceMap` instance: | |
| ```typescript | |
| import { AnyMap } from '@jridgewell/trace-mapping'; | |
| const fooOutput = 'foo'; | |
| const barOutput = 'bar'; | |
| const output = [fooOutput, barOutput].join('\n'); | |
| const sectioned = new AnyMap({ | |
| version: 3, | |
| sections: [ | |
| { | |
| // 0-base line and column | |
| offset: { line: 0, column: 0 }, | |
| // fooOutput's sourcemap | |
| map: { | |
| version: 3, | |
| sources: ['foo.js'], | |
| names: ['foo'], | |
| mappings: 'AAAAA', | |
| }, | |
| }, | |
| { | |
| // barOutput's sourcemap will not affect the first line, only the second | |
| offset: { line: 1, column: 0 }, | |
| map: { | |
| version: 3, | |
| sources: ['bar.js'], | |
| names: ['bar'], | |
| mappings: 'AAAAA', | |
| }, | |
| }, | |
| ], | |
| }); | |
| const traced = originalPositionFor(sectioned, { | |
| line: 2, | |
| column: 0, | |
| }); | |
| assert.deepEqual(traced, { | |
| source: 'bar.js', | |
| line: 1, | |
| column: 0, | |
| name: 'bar', | |
| }); | |
| ``` | |
| ## Benchmarks | |
| ``` | |
| node v20.10.0 | |
| amp.js.map - 45120 segments | |
| Memory Usage: | |
| trace-mapping decoded 414164 bytes | |
| trace-mapping encoded 6274352 bytes | |
| source-map-js 10968904 bytes | |
| source-map-0.6.1 17587160 bytes | |
| source-map-0.8.0 8812155 bytes | |
| Chrome dev tools 8672912 bytes | |
| Smallest memory usage is trace-mapping decoded | |
| Init speed: | |
| trace-mapping: decoded JSON input x 205 ops/sec ±0.19% (88 runs sampled) | |
| trace-mapping: encoded JSON input x 405 ops/sec ±1.47% (88 runs sampled) | |
| trace-mapping: decoded Object input x 4,645 ops/sec ±0.15% (98 runs sampled) | |
| trace-mapping: encoded Object input x 458 ops/sec ±1.63% (91 runs sampled) | |
| source-map-js: encoded Object input x 75.48 ops/sec ±1.64% (67 runs sampled) | |
| source-map-0.6.1: encoded Object input x 39.37 ops/sec ±1.44% (53 runs sampled) | |
| Chrome dev tools: encoded Object input x 150 ops/sec ±1.76% (79 runs sampled) | |
| Fastest is trace-mapping: decoded Object input | |
| Trace speed (random): | |
| trace-mapping: decoded originalPositionFor x 44,946 ops/sec ±0.16% (99 runs sampled) | |
| trace-mapping: encoded originalPositionFor x 37,995 ops/sec ±1.81% (89 runs sampled) | |
| source-map-js: encoded originalPositionFor x 9,230 ops/sec ±1.36% (93 runs sampled) | |
| source-map-0.6.1: encoded originalPositionFor x 8,057 ops/sec ±0.84% (96 runs sampled) | |
| source-map-0.8.0: encoded originalPositionFor x 28,198 ops/sec ±1.12% (91 runs sampled) | |
| Chrome dev tools: encoded originalPositionFor x 46,276 ops/sec ±1.35% (95 runs sampled) | |
| Fastest is Chrome dev tools: encoded originalPositionFor | |
| Trace speed (ascending): | |
| trace-mapping: decoded originalPositionFor x 204,406 ops/sec ±0.19% (97 runs sampled) | |
| trace-mapping: encoded originalPositionFor x 196,695 ops/sec ±0.24% (99 runs sampled) | |
| source-map-js: encoded originalPositionFor x 11,948 ops/sec ±0.94% (99 runs sampled) | |
| source-map-0.6.1: encoded originalPositionFor x 10,730 ops/sec ±0.36% (100 runs sampled) | |
| source-map-0.8.0: encoded originalPositionFor x 51,427 ops/sec ±0.21% (98 runs sampled) | |
| Chrome dev tools: encoded originalPositionFor x 162,615 ops/sec ±0.18% (98 runs sampled) | |
| Fastest is trace-mapping: decoded originalPositionFor | |
| *** | |
| babel.min.js.map - 347793 segments | |
| Memory Usage: | |
| trace-mapping decoded 18504 bytes | |
| trace-mapping encoded 35428008 bytes | |
| source-map-js 51676808 bytes | |
| source-map-0.6.1 63367136 bytes | |
| source-map-0.8.0 43158400 bytes | |
| Chrome dev tools 50721552 bytes | |
| Smallest memory usage is trace-mapping decoded | |
| Init speed: | |
| trace-mapping: decoded JSON input x 17.82 ops/sec ±6.35% (35 runs sampled) | |
| trace-mapping: encoded JSON input x 31.57 ops/sec ±7.50% (43 runs sampled) | |
| trace-mapping: decoded Object input x 867 ops/sec ±0.74% (94 runs sampled) | |
| trace-mapping: encoded Object input x 33.83 ops/sec ±7.66% (46 runs sampled) | |
| source-map-js: encoded Object input x 6.58 ops/sec ±3.31% (20 runs sampled) | |
| source-map-0.6.1: encoded Object input x 4.23 ops/sec ±3.43% (15 runs sampled) | |
| Chrome dev tools: encoded Object input x 22.14 ops/sec ±3.79% (41 runs sampled) | |
| Fastest is trace-mapping: decoded Object input | |
| Trace speed (random): | |
| trace-mapping: decoded originalPositionFor x 78,234 ops/sec ±1.48% (29 runs sampled) | |
| trace-mapping: encoded originalPositionFor x 60,761 ops/sec ±1.35% (21 runs sampled) | |
| source-map-js: encoded originalPositionFor x 51,448 ops/sec ±2.17% (89 runs sampled) | |
| source-map-0.6.1: encoded originalPositionFor x 47,221 ops/sec ±1.99% (15 runs sampled) | |
| source-map-0.8.0: encoded originalPositionFor x 84,002 ops/sec ±1.45% (27 runs sampled) | |
| Chrome dev tools: encoded originalPositionFor x 106,457 ops/sec ±1.38% (37 runs sampled) | |
| Fastest is Chrome dev tools: encoded originalPositionFor | |
| Trace speed (ascending): | |
| trace-mapping: decoded originalPositionFor x 930,943 ops/sec ±0.25% (99 runs sampled) | |
| trace-mapping: encoded originalPositionFor x 843,545 ops/sec ±0.34% (97 runs sampled) | |
| source-map-js: encoded originalPositionFor x 114,510 ops/sec ±1.37% (36 runs sampled) | |
| source-map-0.6.1: encoded originalPositionFor x 87,412 ops/sec ±0.72% (92 runs sampled) | |
| source-map-0.8.0: encoded originalPositionFor x 197,709 ops/sec ±0.89% (59 runs sampled) | |
| Chrome dev tools: encoded originalPositionFor x 688,983 ops/sec ±0.33% (98 runs sampled) | |
| Fastest is trace-mapping: decoded originalPositionFor | |
| *** | |
| preact.js.map - 1992 segments | |
| Memory Usage: | |
| trace-mapping decoded 33136 bytes | |
| trace-mapping encoded 254240 bytes | |
| source-map-js 837488 bytes | |
| source-map-0.6.1 961928 bytes | |
| source-map-0.8.0 54384 bytes | |
| Chrome dev tools 709680 bytes | |
| Smallest memory usage is trace-mapping decoded | |
| Init speed: | |
| trace-mapping: decoded JSON input x 3,709 ops/sec ±0.13% (99 runs sampled) | |
| trace-mapping: encoded JSON input x 6,447 ops/sec ±0.22% (101 runs sampled) | |
| trace-mapping: decoded Object input x 83,062 ops/sec ±0.23% (100 runs sampled) | |
| trace-mapping: encoded Object input x 14,980 ops/sec ±0.28% (100 runs sampled) | |
| source-map-js: encoded Object input x 2,544 ops/sec ±0.16% (99 runs sampled) | |
| source-map-0.6.1: encoded Object input x 1,221 ops/sec ±0.37% (97 runs sampled) | |
| Chrome dev tools: encoded Object input x 4,241 ops/sec ±0.39% (93 runs sampled) | |
| Fastest is trace-mapping: decoded Object input | |
| Trace speed (random): | |
| trace-mapping: decoded originalPositionFor x 91,028 ops/sec ±0.14% (94 runs sampled) | |
| trace-mapping: encoded originalPositionFor x 84,348 ops/sec ±0.26% (98 runs sampled) | |
| source-map-js: encoded originalPositionFor x 26,998 ops/sec ±0.23% (98 runs sampled) | |
| source-map-0.6.1: encoded originalPositionFor x 18,049 ops/sec ±0.26% (100 runs sampled) | |
| source-map-0.8.0: encoded originalPositionFor x 41,916 ops/sec ±0.28% (98 runs sampled) | |
| Chrome dev tools: encoded originalPositionFor x 88,616 ops/sec ±0.14% (98 runs sampled) | |
| Fastest is trace-mapping: decoded originalPositionFor | |
| Trace speed (ascending): | |
| trace-mapping: decoded originalPositionFor x 319,960 ops/sec ±0.16% (100 runs sampled) | |
| trace-mapping: encoded originalPositionFor x 302,153 ops/sec ±0.18% (100 runs sampled) | |
| source-map-js: encoded originalPositionFor x 35,574 ops/sec ±0.19% (100 runs sampled) | |
| source-map-0.6.1: encoded originalPositionFor x 19,943 ops/sec ±0.12% (101 runs sampled) | |
| source-map-0.8.0: encoded originalPositionFor x 54,648 ops/sec ±0.20% (99 runs sampled) | |
| Chrome dev tools: encoded originalPositionFor x 278,319 ops/sec ±0.17% (102 runs sampled) | |
| Fastest is trace-mapping: decoded originalPositionFor | |
| *** | |
| react.js.map - 5726 segments | |
| Memory Usage: | |
| trace-mapping decoded 10872 bytes | |
| trace-mapping encoded 681512 bytes | |
| source-map-js 2563944 bytes | |
| source-map-0.6.1 2150864 bytes | |
| source-map-0.8.0 88680 bytes | |
| Chrome dev tools 1149576 bytes | |
| Smallest memory usage is trace-mapping decoded | |
| Init speed: | |
| trace-mapping: decoded JSON input x 1,887 ops/sec ±0.28% (99 runs sampled) | |
| trace-mapping: encoded JSON input x 4,749 ops/sec ±0.48% (97 runs sampled) | |
| trace-mapping: decoded Object input x 74,236 ops/sec ±0.11% (99 runs sampled) | |
| trace-mapping: encoded Object input x 5,752 ops/sec ±0.38% (100 runs sampled) | |
| source-map-js: encoded Object input x 806 ops/sec ±0.19% (97 runs sampled) | |
| source-map-0.6.1: encoded Object input x 418 ops/sec ±0.33% (94 runs sampled) | |
| Chrome dev tools: encoded Object input x 1,524 ops/sec ±0.57% (92 runs sampled) | |
| Fastest is trace-mapping: decoded Object input | |
| Trace speed (random): | |
| trace-mapping: decoded originalPositionFor x 620,201 ops/sec ±0.33% (96 runs sampled) | |
| trace-mapping: encoded originalPositionFor x 579,548 ops/sec ±0.35% (97 runs sampled) | |
| source-map-js: encoded originalPositionFor x 230,983 ops/sec ±0.62% (54 runs sampled) | |
| source-map-0.6.1: encoded originalPositionFor x 158,145 ops/sec ±0.80% (46 runs sampled) | |
| source-map-0.8.0: encoded originalPositionFor x 343,801 ops/sec ±0.55% (96 runs sampled) | |
| Chrome dev tools: encoded originalPositionFor x 659,649 ops/sec ±0.49% (98 runs sampled) | |
| Fastest is Chrome dev tools: encoded originalPositionFor | |
| Trace speed (ascending): | |
| trace-mapping: decoded originalPositionFor x 2,368,079 ops/sec ±0.32% (98 runs sampled) | |
| trace-mapping: encoded originalPositionFor x 2,134,039 ops/sec ±2.72% (87 runs sampled) | |
| source-map-js: encoded originalPositionFor x 290,120 ops/sec ±2.49% (82 runs sampled) | |
| source-map-0.6.1: encoded originalPositionFor x 187,613 ops/sec ±0.86% (49 runs sampled) | |
| source-map-0.8.0: encoded originalPositionFor x 479,569 ops/sec ±0.65% (96 runs sampled) | |
| Chrome dev tools: encoded originalPositionFor x 2,048,414 ops/sec ±0.24% (98 runs sampled) | |
| Fastest is trace-mapping: decoded originalPositionFor | |
| *** | |
| vscode.map - 2141001 segments | |
| Memory Usage: | |
| trace-mapping decoded 5206584 bytes | |
| trace-mapping encoded 208370336 bytes | |
| source-map-js 278493008 bytes | |
| source-map-0.6.1 391564048 bytes | |
| source-map-0.8.0 257508787 bytes | |
| Chrome dev tools 291053000 bytes | |
| Smallest memory usage is trace-mapping decoded | |
| Init speed: | |
| trace-mapping: decoded JSON input x 1.63 ops/sec ±33.88% (9 runs sampled) | |
| trace-mapping: encoded JSON input x 3.29 ops/sec ±36.13% (13 runs sampled) | |
| trace-mapping: decoded Object input x 103 ops/sec ±0.93% (77 runs sampled) | |
| trace-mapping: encoded Object input x 5.42 ops/sec ±28.54% (19 runs sampled) | |
| source-map-js: encoded Object input x 1.07 ops/sec ±13.84% (7 runs sampled) | |
| source-map-0.6.1: encoded Object input x 0.60 ops/sec ±2.43% (6 runs sampled) | |
| Chrome dev tools: encoded Object input x 2.61 ops/sec ±22.00% (11 runs sampled) | |
| Fastest is trace-mapping: decoded Object input | |
| Trace speed (random): | |
| trace-mapping: decoded originalPositionFor x 257,019 ops/sec ±0.97% (93 runs sampled) | |
| trace-mapping: encoded originalPositionFor x 179,163 ops/sec ±0.83% (92 runs sampled) | |
| source-map-js: encoded originalPositionFor x 73,337 ops/sec ±1.35% (87 runs sampled) | |
| source-map-0.6.1: encoded originalPositionFor x 38,797 ops/sec ±1.66% (88 runs sampled) | |
| source-map-0.8.0: encoded originalPositionFor x 107,758 ops/sec ±1.94% (45 runs sampled) | |
| Chrome dev tools: encoded originalPositionFor x 188,550 ops/sec ±1.85% (79 runs sampled) | |
| Fastest is trace-mapping: decoded originalPositionFor | |
| Trace speed (ascending): | |
| trace-mapping: decoded originalPositionFor x 447,621 ops/sec ±3.64% (94 runs sampled) | |
| trace-mapping: encoded originalPositionFor x 323,698 ops/sec ±5.20% (88 runs sampled) | |
| source-map-js: encoded originalPositionFor x 78,387 ops/sec ±1.69% (89 runs sampled) | |
| source-map-0.6.1: encoded originalPositionFor x 41,016 ops/sec ±3.01% (25 runs sampled) | |
| source-map-0.8.0: encoded originalPositionFor x 124,204 ops/sec ±0.90% (92 runs sampled) | |
| Chrome dev tools: encoded originalPositionFor x 230,087 ops/sec ±2.61% (93 runs sampled) | |
| Fastest is trace-mapping: decoded originalPositionFor | |
| ``` | |
| [source-map]: https://www.npmjs.com/package/source-map | |