Debian Codegraph @

jridgewell-gen-mapping/README.md

raw
1 # @jridgewell/gen-mapping
2
3 > Generate source maps
4
5 `gen-mapping` allows you to generate a source map during transpilation or minification.
6 With a source map, you're able to trace the original location in the source file, either in Chrome's
7 DevTools or using a library like [`@jridgewell/trace-mapping`][trace-mapping].
8
9 You may already be familiar with the [`source-map`][source-map] package's `SourceMapGenerator`. This
10 provides the same `addMapping` and `setSourceContent` API.
11
12 ## Installation
13
14 ```sh
15 npm install @jridgewell/gen-mapping
16 ```
17
18 ## Usage
19
20 ```typescript
21 import { GenMapping, addMapping, setSourceContent, toEncodedMap, toDecodedMap } from '@jridgewell/gen-mapping';
22
23 const map = new GenMapping({
24 file: 'output.js',
25 sourceRoot: 'https://example.com/',
26 });
27
28 setSourceContent(map, 'input.js', `function foo() {}`);
29
30 addMapping(map, {
31 // Lines start at line 1, columns at column 0.
32 generated: { line: 1, column: 0 },
33 source: 'input.js',
34 original: { line: 1, column: 0 },
35 });
36
37 addMapping(map, {
38 generated: { line: 1, column: 9 },
39 source: 'input.js',
40 original: { line: 1, column: 9 },
41 name: 'foo',
42 });
43
44 assert.deepEqual(toDecodedMap(map), {
45 version: 3,
46 file: 'output.js',
47 names: ['foo'],
48 sourceRoot: 'https://example.com/',
49 sources: ['input.js'],
50 sourcesContent: ['function foo() {}'],
51 mappings: [
52 [ [0, 0, 0, 0], [9, 0, 0, 9, 0] ]
53 ],
54 });
55
56 assert.deepEqual(toEncodedMap(map), {
57 version: 3,
58 file: 'output.js',
59 names: ['foo'],
60 sourceRoot: 'https://example.com/',
61 sources: ['input.js'],
62 sourcesContent: ['function foo() {}'],
63 mappings: 'AAAA,SAASA',
64 });
65 ```
66
67 ### Smaller Sourcemaps
68
69 Not everything needs to be added to a sourcemap, and needless markings can cause signficantly
70 larger file sizes. `gen-mapping` exposes `maybeAddSegment`/`maybeAddMapping` APIs that will
71 intelligently determine if this marking adds useful information. If not, the marking will be
72 skipped.
73
74 ```typescript
75 import { maybeAddMapping } from '@jridgewell/gen-mapping';
76
77 const map = new GenMapping();
78
79 // Adding a sourceless marking at the beginning of a line isn't useful.
80 maybeAddMapping(map, {
81 generated: { line: 1, column: 0 },
82 });
83
84 // Adding a new source marking is useful.
85 maybeAddMapping(map, {
86 generated: { line: 1, column: 0 },
87 source: 'input.js',
88 original: { line: 1, column: 0 },
89 });
90
91 // But adding another marking pointing to the exact same original location isn't, even if the
92 // generated column changed.
93 maybeAddMapping(map, {
94 generated: { line: 1, column: 9 },
95 source: 'input.js',
96 original: { line: 1, column: 0 },
97 });
98
99 assert.deepEqual(toEncodedMap(map), {
100 version: 3,
101 names: [],
102 sources: ['input.js'],
103 sourcesContent: [null],
104 mappings: 'AAAA',
105 });
106 ```
107
108 ## Benchmarks
109
110 ```
111 node v18.0.0
112
113 amp.js.map
114 Memory Usage:
115 gen-mapping: addSegment 5852872 bytes
116 gen-mapping: addMapping 7716042 bytes
117 source-map-js 6143250 bytes
118 source-map-0.6.1 6124102 bytes
119 source-map-0.8.0 6121173 bytes
120 Smallest memory usage is gen-mapping: addSegment
121
122 Adding speed:
123 gen-mapping: addSegment x 441 ops/sec ±2.07% (90 runs sampled)
124 gen-mapping: addMapping x 350 ops/sec ±2.40% (86 runs sampled)
125 source-map-js: addMapping x 169 ops/sec ±2.42% (80 runs sampled)
126 source-map-0.6.1: addMapping x 167 ops/sec ±2.56% (80 runs sampled)
127 source-map-0.8.0: addMapping x 168 ops/sec ±2.52% (80 runs sampled)
128 Fastest is gen-mapping: addSegment
129
130 Generate speed:
131 gen-mapping: decoded output x 150,824,370 ops/sec ±0.07% (102 runs sampled)
132 gen-mapping: encoded output x 663 ops/sec ±0.22% (98 runs sampled)
133 source-map-js: encoded output x 197 ops/sec ±0.45% (84 runs sampled)
134 source-map-0.6.1: encoded output x 198 ops/sec ±0.33% (85 runs sampled)
135 source-map-0.8.0: encoded output x 197 ops/sec ±0.06% (93 runs sampled)
136 Fastest is gen-mapping: decoded output
137
138
139 ***
140
141
142 babel.min.js.map
143 Memory Usage:
144 gen-mapping: addSegment 37578063 bytes
145 gen-mapping: addMapping 37212897 bytes
146 source-map-js 47638527 bytes
147 source-map-0.6.1 47690503 bytes
148 source-map-0.8.0 47470188 bytes
149 Smallest memory usage is gen-mapping: addMapping
150
151 Adding speed:
152 gen-mapping: addSegment x 31.05 ops/sec ±8.31% (43 runs sampled)
153 gen-mapping: addMapping x 29.83 ops/sec ±7.36% (51 runs sampled)
154 source-map-js: addMapping x 20.73 ops/sec ±6.22% (38 runs sampled)
155 source-map-0.6.1: addMapping x 20.03 ops/sec ±10.51% (38 runs sampled)
156 source-map-0.8.0: addMapping x 19.30 ops/sec ±8.27% (37 runs sampled)
157 Fastest is gen-mapping: addSegment
158
159 Generate speed:
160 gen-mapping: decoded output x 381,379,234 ops/sec ±0.29% (96 runs sampled)
161 gen-mapping: encoded output x 95.15 ops/sec ±2.98% (72 runs sampled)
162 source-map-js: encoded output x 15.20 ops/sec ±7.41% (33 runs sampled)
163 source-map-0.6.1: encoded output x 16.36 ops/sec ±10.46% (31 runs sampled)
164 source-map-0.8.0: encoded output x 16.06 ops/sec ±6.45% (31 runs sampled)
165 Fastest is gen-mapping: decoded output
166
167
168 ***
169
170
171 preact.js.map
172 Memory Usage:
173 gen-mapping: addSegment 416247 bytes
174 gen-mapping: addMapping 419824 bytes
175 source-map-js 1024619 bytes
176 source-map-0.6.1 1146004 bytes
177 source-map-0.8.0 1113250 bytes
178 Smallest memory usage is gen-mapping: addSegment
179
180 Adding speed:
181 gen-mapping: addSegment x 13,755 ops/sec ±0.15% (98 runs sampled)
182 gen-mapping: addMapping x 13,013 ops/sec ±0.11% (101 runs sampled)
183 source-map-js: addMapping x 4,564 ops/sec ±0.21% (98 runs sampled)
184 source-map-0.6.1: addMapping x 4,562 ops/sec ±0.11% (99 runs sampled)
185 source-map-0.8.0: addMapping x 4,593 ops/sec ±0.11% (100 runs sampled)
186 Fastest is gen-mapping: addSegment
187
188 Generate speed:
189 gen-mapping: decoded output x 379,864,020 ops/sec ±0.23% (93 runs sampled)
190 gen-mapping: encoded output x 14,368 ops/sec ±4.07% (82 runs sampled)
191 source-map-js: encoded output x 5,261 ops/sec ±0.21% (99 runs sampled)
192 source-map-0.6.1: encoded output x 5,124 ops/sec ±0.58% (99 runs sampled)
193 source-map-0.8.0: encoded output x 5,434 ops/sec ±0.33% (96 runs sampled)
194 Fastest is gen-mapping: decoded output
195
196
197 ***
198
199
200 react.js.map
201 Memory Usage:
202 gen-mapping: addSegment 975096 bytes
203 gen-mapping: addMapping 1102981 bytes
204 source-map-js 2918836 bytes
205 source-map-0.6.1 2885435 bytes
206 source-map-0.8.0 2874336 bytes
207 Smallest memory usage is gen-mapping: addSegment
208
209 Adding speed:
210 gen-mapping: addSegment x 4,772 ops/sec ±0.15% (100 runs sampled)
211 gen-mapping: addMapping x 4,456 ops/sec ±0.13% (97 runs sampled)
212 source-map-js: addMapping x 1,618 ops/sec ±0.24% (97 runs sampled)
213 source-map-0.6.1: addMapping x 1,622 ops/sec ±0.12% (99 runs sampled)
214 source-map-0.8.0: addMapping x 1,631 ops/sec ±0.12% (100 runs sampled)
215 Fastest is gen-mapping: addSegment
216
217 Generate speed:
218 gen-mapping: decoded output x 379,107,695 ops/sec ±0.07% (99 runs sampled)
219 gen-mapping: encoded output x 5,421 ops/sec ±1.60% (89 runs sampled)
220 source-map-js: encoded output x 2,113 ops/sec ±1.81% (98 runs sampled)
221 source-map-0.6.1: encoded output x 2,126 ops/sec ±0.10% (100 runs sampled)
222 source-map-0.8.0: encoded output x 2,176 ops/sec ±0.39% (98 runs sampled)
223 Fastest is gen-mapping: decoded output
224 ```
225
226 [source-map]: https://www.npmjs.com/package/source-map
227 [trace-mapping]: https://github.com/jridgewell/trace-mapping