| 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 |