source: frontend/node_modules/@jridgewell/trace-mapping/README.md

Last change on this file was 9af201e, checked in by MBK <marija.karapandzova@…>, 2 weeks ago

Fix frontend appearance
  • Property mode set to 100644
File size: 14.1 KB
Line 
1# @jridgewell/trace-mapping
2
3> Trace the original position through a source map
4
5`trace-mapping` allows you to take the line and column of an output file and trace it to the
6original location in the source file through a source map.
7
8You may already be familiar with the [`source-map`][source-map] package's `SourceMapConsumer`. This
9provides the same `originalPositionFor` and `generatedPositionFor` API, without requiring WASM.
10
11## Installation
12
13```sh
14npm install @jridgewell/trace-mapping
15```
16
17## Usage
18
19```typescript
20import {
21 TraceMap,
22 originalPositionFor,
23 generatedPositionFor,
24 sourceContentFor,
25 isIgnored,
26} from '@jridgewell/trace-mapping';
27
28const tracer = new TraceMap({
29 version: 3,
30 sources: ['input.js'],
31 sourcesContent: ['content of input.js'],
32 names: ['foo'],
33 mappings: 'KAyCIA',
34 ignoreList: [],
35});
36
37// Lines start at line 1, columns at column 0.
38const traced = originalPositionFor(tracer, { line: 1, column: 5 });
39assert.deepEqual(traced, {
40 source: 'input.js',
41 line: 42,
42 column: 4,
43 name: 'foo',
44});
45
46const content = sourceContentFor(tracer, traced.source);
47assert.strictEqual(content, 'content for input.js');
48
49const generated = generatedPositionFor(tracer, {
50 source: 'input.js',
51 line: 42,
52 column: 4,
53});
54assert.deepEqual(generated, {
55 line: 1,
56 column: 5,
57});
58
59const ignored = isIgnored(tracer, 'input.js');
60assert.equal(ignored, false);
61```
62
63We also provide a lower level API to get the actual segment that matches our line and column. Unlike
64`originalPositionFor`, `traceSegment` uses a 0-base for `line`:
65
66```typescript
67import { traceSegment } from '@jridgewell/trace-mapping';
68
69// line is 0-base.
70const traced = traceSegment(tracer, /* line */ 0, /* column */ 5);
71
72// Segments are [outputColumn, sourcesIndex, sourceLine, sourceColumn, namesIndex]
73// Again, line is 0-base and so is sourceLine
74assert.deepEqual(traced, [5, 0, 41, 4, 0]);
75```
76
77### SectionedSourceMaps
78
79The sourcemap spec defines a special `sections` field that's designed to handle concatenation of
80output code with associated sourcemaps. This type of sourcemap is rarely used (no major build tool
81produces it), but if you are hand coding a concatenation you may need it. We provide an `AnyMap`
82helper that can receive either a regular sourcemap or a `SectionedSourceMap` and returns a
83`TraceMap` instance:
84
85```typescript
86import { AnyMap } from '@jridgewell/trace-mapping';
87const fooOutput = 'foo';
88const barOutput = 'bar';
89const output = [fooOutput, barOutput].join('\n');
90
91const sectioned = new AnyMap({
92 version: 3,
93 sections: [
94 {
95 // 0-base line and column
96 offset: { line: 0, column: 0 },
97 // fooOutput's sourcemap
98 map: {
99 version: 3,
100 sources: ['foo.js'],
101 names: ['foo'],
102 mappings: 'AAAAA',
103 },
104 },
105 {
106 // barOutput's sourcemap will not affect the first line, only the second
107 offset: { line: 1, column: 0 },
108 map: {
109 version: 3,
110 sources: ['bar.js'],
111 names: ['bar'],
112 mappings: 'AAAAA',
113 },
114 },
115 ],
116});
117
118const traced = originalPositionFor(sectioned, {
119 line: 2,
120 column: 0,
121});
122
123assert.deepEqual(traced, {
124 source: 'bar.js',
125 line: 1,
126 column: 0,
127 name: 'bar',
128});
129```
130
131## Benchmarks
132
133```
134node v20.10.0
135
136amp.js.map - 45120 segments
137
138Memory Usage:
139trace-mapping decoded 414164 bytes
140trace-mapping encoded 6274352 bytes
141source-map-js 10968904 bytes
142source-map-0.6.1 17587160 bytes
143source-map-0.8.0 8812155 bytes
144Chrome dev tools 8672912 bytes
145Smallest memory usage is trace-mapping decoded
146
147Init speed:
148trace-mapping: decoded JSON input x 205 ops/sec ±0.19% (88 runs sampled)
149trace-mapping: encoded JSON input x 405 ops/sec ±1.47% (88 runs sampled)
150trace-mapping: decoded Object input x 4,645 ops/sec ±0.15% (98 runs sampled)
151trace-mapping: encoded Object input x 458 ops/sec ±1.63% (91 runs sampled)
152source-map-js: encoded Object input x 75.48 ops/sec ±1.64% (67 runs sampled)
153source-map-0.6.1: encoded Object input x 39.37 ops/sec ±1.44% (53 runs sampled)
154Chrome dev tools: encoded Object input x 150 ops/sec ±1.76% (79 runs sampled)
155Fastest is trace-mapping: decoded Object input
156
157Trace speed (random):
158trace-mapping: decoded originalPositionFor x 44,946 ops/sec ±0.16% (99 runs sampled)
159trace-mapping: encoded originalPositionFor x 37,995 ops/sec ±1.81% (89 runs sampled)
160source-map-js: encoded originalPositionFor x 9,230 ops/sec ±1.36% (93 runs sampled)
161source-map-0.6.1: encoded originalPositionFor x 8,057 ops/sec ±0.84% (96 runs sampled)
162source-map-0.8.0: encoded originalPositionFor x 28,198 ops/sec ±1.12% (91 runs sampled)
163Chrome dev tools: encoded originalPositionFor x 46,276 ops/sec ±1.35% (95 runs sampled)
164Fastest is Chrome dev tools: encoded originalPositionFor
165
166Trace speed (ascending):
167trace-mapping: decoded originalPositionFor x 204,406 ops/sec ±0.19% (97 runs sampled)
168trace-mapping: encoded originalPositionFor x 196,695 ops/sec ±0.24% (99 runs sampled)
169source-map-js: encoded originalPositionFor x 11,948 ops/sec ±0.94% (99 runs sampled)
170source-map-0.6.1: encoded originalPositionFor x 10,730 ops/sec ±0.36% (100 runs sampled)
171source-map-0.8.0: encoded originalPositionFor x 51,427 ops/sec ±0.21% (98 runs sampled)
172Chrome dev tools: encoded originalPositionFor x 162,615 ops/sec ±0.18% (98 runs sampled)
173Fastest is trace-mapping: decoded originalPositionFor
174
175
176***
177
178
179babel.min.js.map - 347793 segments
180
181Memory Usage:
182trace-mapping decoded 18504 bytes
183trace-mapping encoded 35428008 bytes
184source-map-js 51676808 bytes
185source-map-0.6.1 63367136 bytes
186source-map-0.8.0 43158400 bytes
187Chrome dev tools 50721552 bytes
188Smallest memory usage is trace-mapping decoded
189
190Init speed:
191trace-mapping: decoded JSON input x 17.82 ops/sec ±6.35% (35 runs sampled)
192trace-mapping: encoded JSON input x 31.57 ops/sec ±7.50% (43 runs sampled)
193trace-mapping: decoded Object input x 867 ops/sec ±0.74% (94 runs sampled)
194trace-mapping: encoded Object input x 33.83 ops/sec ±7.66% (46 runs sampled)
195source-map-js: encoded Object input x 6.58 ops/sec ±3.31% (20 runs sampled)
196source-map-0.6.1: encoded Object input x 4.23 ops/sec ±3.43% (15 runs sampled)
197Chrome dev tools: encoded Object input x 22.14 ops/sec ±3.79% (41 runs sampled)
198Fastest is trace-mapping: decoded Object input
199
200Trace speed (random):
201trace-mapping: decoded originalPositionFor x 78,234 ops/sec ±1.48% (29 runs sampled)
202trace-mapping: encoded originalPositionFor x 60,761 ops/sec ±1.35% (21 runs sampled)
203source-map-js: encoded originalPositionFor x 51,448 ops/sec ±2.17% (89 runs sampled)
204source-map-0.6.1: encoded originalPositionFor x 47,221 ops/sec ±1.99% (15 runs sampled)
205source-map-0.8.0: encoded originalPositionFor x 84,002 ops/sec ±1.45% (27 runs sampled)
206Chrome dev tools: encoded originalPositionFor x 106,457 ops/sec ±1.38% (37 runs sampled)
207Fastest is Chrome dev tools: encoded originalPositionFor
208
209Trace speed (ascending):
210trace-mapping: decoded originalPositionFor x 930,943 ops/sec ±0.25% (99 runs sampled)
211trace-mapping: encoded originalPositionFor x 843,545 ops/sec ±0.34% (97 runs sampled)
212source-map-js: encoded originalPositionFor x 114,510 ops/sec ±1.37% (36 runs sampled)
213source-map-0.6.1: encoded originalPositionFor x 87,412 ops/sec ±0.72% (92 runs sampled)
214source-map-0.8.0: encoded originalPositionFor x 197,709 ops/sec ±0.89% (59 runs sampled)
215Chrome dev tools: encoded originalPositionFor x 688,983 ops/sec ±0.33% (98 runs sampled)
216Fastest is trace-mapping: decoded originalPositionFor
217
218
219***
220
221
222preact.js.map - 1992 segments
223
224Memory Usage:
225trace-mapping decoded 33136 bytes
226trace-mapping encoded 254240 bytes
227source-map-js 837488 bytes
228source-map-0.6.1 961928 bytes
229source-map-0.8.0 54384 bytes
230Chrome dev tools 709680 bytes
231Smallest memory usage is trace-mapping decoded
232
233Init speed:
234trace-mapping: decoded JSON input x 3,709 ops/sec ±0.13% (99 runs sampled)
235trace-mapping: encoded JSON input x 6,447 ops/sec ±0.22% (101 runs sampled)
236trace-mapping: decoded Object input x 83,062 ops/sec ±0.23% (100 runs sampled)
237trace-mapping: encoded Object input x 14,980 ops/sec ±0.28% (100 runs sampled)
238source-map-js: encoded Object input x 2,544 ops/sec ±0.16% (99 runs sampled)
239source-map-0.6.1: encoded Object input x 1,221 ops/sec ±0.37% (97 runs sampled)
240Chrome dev tools: encoded Object input x 4,241 ops/sec ±0.39% (93 runs sampled)
241Fastest is trace-mapping: decoded Object input
242
243Trace speed (random):
244trace-mapping: decoded originalPositionFor x 91,028 ops/sec ±0.14% (94 runs sampled)
245trace-mapping: encoded originalPositionFor x 84,348 ops/sec ±0.26% (98 runs sampled)
246source-map-js: encoded originalPositionFor x 26,998 ops/sec ±0.23% (98 runs sampled)
247source-map-0.6.1: encoded originalPositionFor x 18,049 ops/sec ±0.26% (100 runs sampled)
248source-map-0.8.0: encoded originalPositionFor x 41,916 ops/sec ±0.28% (98 runs sampled)
249Chrome dev tools: encoded originalPositionFor x 88,616 ops/sec ±0.14% (98 runs sampled)
250Fastest is trace-mapping: decoded originalPositionFor
251
252Trace speed (ascending):
253trace-mapping: decoded originalPositionFor x 319,960 ops/sec ±0.16% (100 runs sampled)
254trace-mapping: encoded originalPositionFor x 302,153 ops/sec ±0.18% (100 runs sampled)
255source-map-js: encoded originalPositionFor x 35,574 ops/sec ±0.19% (100 runs sampled)
256source-map-0.6.1: encoded originalPositionFor x 19,943 ops/sec ±0.12% (101 runs sampled)
257source-map-0.8.0: encoded originalPositionFor x 54,648 ops/sec ±0.20% (99 runs sampled)
258Chrome dev tools: encoded originalPositionFor x 278,319 ops/sec ±0.17% (102 runs sampled)
259Fastest is trace-mapping: decoded originalPositionFor
260
261
262***
263
264
265react.js.map - 5726 segments
266
267Memory Usage:
268trace-mapping decoded 10872 bytes
269trace-mapping encoded 681512 bytes
270source-map-js 2563944 bytes
271source-map-0.6.1 2150864 bytes
272source-map-0.8.0 88680 bytes
273Chrome dev tools 1149576 bytes
274Smallest memory usage is trace-mapping decoded
275
276Init speed:
277trace-mapping: decoded JSON input x 1,887 ops/sec ±0.28% (99 runs sampled)
278trace-mapping: encoded JSON input x 4,749 ops/sec ±0.48% (97 runs sampled)
279trace-mapping: decoded Object input x 74,236 ops/sec ±0.11% (99 runs sampled)
280trace-mapping: encoded Object input x 5,752 ops/sec ±0.38% (100 runs sampled)
281source-map-js: encoded Object input x 806 ops/sec ±0.19% (97 runs sampled)
282source-map-0.6.1: encoded Object input x 418 ops/sec ±0.33% (94 runs sampled)
283Chrome dev tools: encoded Object input x 1,524 ops/sec ±0.57% (92 runs sampled)
284Fastest is trace-mapping: decoded Object input
285
286Trace speed (random):
287trace-mapping: decoded originalPositionFor x 620,201 ops/sec ±0.33% (96 runs sampled)
288trace-mapping: encoded originalPositionFor x 579,548 ops/sec ±0.35% (97 runs sampled)
289source-map-js: encoded originalPositionFor x 230,983 ops/sec ±0.62% (54 runs sampled)
290source-map-0.6.1: encoded originalPositionFor x 158,145 ops/sec ±0.80% (46 runs sampled)
291source-map-0.8.0: encoded originalPositionFor x 343,801 ops/sec ±0.55% (96 runs sampled)
292Chrome dev tools: encoded originalPositionFor x 659,649 ops/sec ±0.49% (98 runs sampled)
293Fastest is Chrome dev tools: encoded originalPositionFor
294
295Trace speed (ascending):
296trace-mapping: decoded originalPositionFor x 2,368,079 ops/sec ±0.32% (98 runs sampled)
297trace-mapping: encoded originalPositionFor x 2,134,039 ops/sec ±2.72% (87 runs sampled)
298source-map-js: encoded originalPositionFor x 290,120 ops/sec ±2.49% (82 runs sampled)
299source-map-0.6.1: encoded originalPositionFor x 187,613 ops/sec ±0.86% (49 runs sampled)
300source-map-0.8.0: encoded originalPositionFor x 479,569 ops/sec ±0.65% (96 runs sampled)
301Chrome dev tools: encoded originalPositionFor x 2,048,414 ops/sec ±0.24% (98 runs sampled)
302Fastest is trace-mapping: decoded originalPositionFor
303
304
305***
306
307
308vscode.map - 2141001 segments
309
310Memory Usage:
311trace-mapping decoded 5206584 bytes
312trace-mapping encoded 208370336 bytes
313source-map-js 278493008 bytes
314source-map-0.6.1 391564048 bytes
315source-map-0.8.0 257508787 bytes
316Chrome dev tools 291053000 bytes
317Smallest memory usage is trace-mapping decoded
318
319Init speed:
320trace-mapping: decoded JSON input x 1.63 ops/sec ±33.88% (9 runs sampled)
321trace-mapping: encoded JSON input x 3.29 ops/sec ±36.13% (13 runs sampled)
322trace-mapping: decoded Object input x 103 ops/sec ±0.93% (77 runs sampled)
323trace-mapping: encoded Object input x 5.42 ops/sec ±28.54% (19 runs sampled)
324source-map-js: encoded Object input x 1.07 ops/sec ±13.84% (7 runs sampled)
325source-map-0.6.1: encoded Object input x 0.60 ops/sec ±2.43% (6 runs sampled)
326Chrome dev tools: encoded Object input x 2.61 ops/sec ±22.00% (11 runs sampled)
327Fastest is trace-mapping: decoded Object input
328
329Trace speed (random):
330trace-mapping: decoded originalPositionFor x 257,019 ops/sec ±0.97% (93 runs sampled)
331trace-mapping: encoded originalPositionFor x 179,163 ops/sec ±0.83% (92 runs sampled)
332source-map-js: encoded originalPositionFor x 73,337 ops/sec ±1.35% (87 runs sampled)
333source-map-0.6.1: encoded originalPositionFor x 38,797 ops/sec ±1.66% (88 runs sampled)
334source-map-0.8.0: encoded originalPositionFor x 107,758 ops/sec ±1.94% (45 runs sampled)
335Chrome dev tools: encoded originalPositionFor x 188,550 ops/sec ±1.85% (79 runs sampled)
336Fastest is trace-mapping: decoded originalPositionFor
337
338Trace speed (ascending):
339trace-mapping: decoded originalPositionFor x 447,621 ops/sec ±3.64% (94 runs sampled)
340trace-mapping: encoded originalPositionFor x 323,698 ops/sec ±5.20% (88 runs sampled)
341source-map-js: encoded originalPositionFor x 78,387 ops/sec ±1.69% (89 runs sampled)
342source-map-0.6.1: encoded originalPositionFor x 41,016 ops/sec ±3.01% (25 runs sampled)
343source-map-0.8.0: encoded originalPositionFor x 124,204 ops/sec ±0.90% (92 runs sampled)
344Chrome dev tools: encoded originalPositionFor x 230,087 ops/sec ±2.61% (93 runs sampled)
345Fastest is trace-mapping: decoded originalPositionFor
346```
347
348[source-map]: https://www.npmjs.com/package/source-map
Note: See TracBrowser for help on using the repository browser.