| 1 | # @jridgewell/sourcemap-codec
|
|---|
| 2 |
|
|---|
| 3 | Encode/decode the `mappings` property of a [sourcemap](https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit).
|
|---|
| 4 |
|
|---|
| 5 |
|
|---|
| 6 | ## Why?
|
|---|
| 7 |
|
|---|
| 8 | Sourcemaps are difficult to generate and manipulate, because the `mappings` property – the part that actually links the generated code back to the original source – is encoded using an obscure method called [Variable-length quantity](https://en.wikipedia.org/wiki/Variable-length_quantity). On top of that, each segment in the mapping contains offsets rather than absolute indices, which means that you can't look at a segment in isolation – you have to understand the whole sourcemap.
|
|---|
| 9 |
|
|---|
| 10 | This package makes the process slightly easier.
|
|---|
| 11 |
|
|---|
| 12 |
|
|---|
| 13 | ## Installation
|
|---|
| 14 |
|
|---|
| 15 | ```bash
|
|---|
| 16 | npm install @jridgewell/sourcemap-codec
|
|---|
| 17 | ```
|
|---|
| 18 |
|
|---|
| 19 |
|
|---|
| 20 | ## Usage
|
|---|
| 21 |
|
|---|
| 22 | ```js
|
|---|
| 23 | import { encode, decode } from '@jridgewell/sourcemap-codec';
|
|---|
| 24 |
|
|---|
| 25 | var decoded = decode( ';EAEEA,EAAE,EAAC,CAAE;ECQY,UACC' );
|
|---|
| 26 |
|
|---|
| 27 | assert.deepEqual( decoded, [
|
|---|
| 28 | // the first line (of the generated code) has no mappings,
|
|---|
| 29 | // as shown by the starting semi-colon (which separates lines)
|
|---|
| 30 | [],
|
|---|
| 31 |
|
|---|
| 32 | // the second line contains four (comma-separated) segments
|
|---|
| 33 | [
|
|---|
| 34 | // segments are encoded as you'd expect:
|
|---|
| 35 | // [ generatedCodeColumn, sourceIndex, sourceCodeLine, sourceCodeColumn, nameIndex ]
|
|---|
| 36 |
|
|---|
| 37 | // i.e. the first segment begins at column 2, and maps back to the second column
|
|---|
| 38 | // of the second line (both zero-based) of the 0th source, and uses the 0th
|
|---|
| 39 | // name in the `map.names` array
|
|---|
| 40 | [ 2, 0, 2, 2, 0 ],
|
|---|
| 41 |
|
|---|
| 42 | // the remaining segments are 4-length rather than 5-length,
|
|---|
| 43 | // because they don't map a name
|
|---|
| 44 | [ 4, 0, 2, 4 ],
|
|---|
| 45 | [ 6, 0, 2, 5 ],
|
|---|
| 46 | [ 7, 0, 2, 7 ]
|
|---|
| 47 | ],
|
|---|
| 48 |
|
|---|
| 49 | // the final line contains two segments
|
|---|
| 50 | [
|
|---|
| 51 | [ 2, 1, 10, 19 ],
|
|---|
| 52 | [ 12, 1, 11, 20 ]
|
|---|
| 53 | ]
|
|---|
| 54 | ]);
|
|---|
| 55 |
|
|---|
| 56 | var encoded = encode( decoded );
|
|---|
| 57 | assert.equal( encoded, ';EAEEA,EAAE,EAAC,CAAE;ECQY,UACC' );
|
|---|
| 58 | ```
|
|---|
| 59 |
|
|---|
| 60 | ## Benchmarks
|
|---|
| 61 |
|
|---|
| 62 | ```
|
|---|
| 63 | node v20.10.0
|
|---|
| 64 |
|
|---|
| 65 | amp.js.map - 45120 segments
|
|---|
| 66 |
|
|---|
| 67 | Decode Memory Usage:
|
|---|
| 68 | local code 5815135 bytes
|
|---|
| 69 | @jridgewell/sourcemap-codec 1.4.15 5868160 bytes
|
|---|
| 70 | sourcemap-codec 5492584 bytes
|
|---|
| 71 | source-map-0.6.1 13569984 bytes
|
|---|
| 72 | source-map-0.8.0 6390584 bytes
|
|---|
| 73 | chrome dev tools 8011136 bytes
|
|---|
| 74 | Smallest memory usage is sourcemap-codec
|
|---|
| 75 |
|
|---|
| 76 | Decode speed:
|
|---|
| 77 | decode: local code x 492 ops/sec ±1.22% (90 runs sampled)
|
|---|
| 78 | decode: @jridgewell/sourcemap-codec 1.4.15 x 499 ops/sec ±1.16% (89 runs sampled)
|
|---|
| 79 | decode: sourcemap-codec x 376 ops/sec ±1.66% (89 runs sampled)
|
|---|
| 80 | decode: source-map-0.6.1 x 34.99 ops/sec ±0.94% (48 runs sampled)
|
|---|
| 81 | decode: source-map-0.8.0 x 351 ops/sec ±0.07% (95 runs sampled)
|
|---|
| 82 | chrome dev tools x 165 ops/sec ±0.91% (86 runs sampled)
|
|---|
| 83 | Fastest is decode: @jridgewell/sourcemap-codec 1.4.15
|
|---|
| 84 |
|
|---|
| 85 | Encode Memory Usage:
|
|---|
| 86 | local code 444248 bytes
|
|---|
| 87 | @jridgewell/sourcemap-codec 1.4.15 623024 bytes
|
|---|
| 88 | sourcemap-codec 8696280 bytes
|
|---|
| 89 | source-map-0.6.1 8745176 bytes
|
|---|
| 90 | source-map-0.8.0 8736624 bytes
|
|---|
| 91 | Smallest memory usage is local code
|
|---|
| 92 |
|
|---|
| 93 | Encode speed:
|
|---|
| 94 | encode: local code x 796 ops/sec ±0.11% (97 runs sampled)
|
|---|
| 95 | encode: @jridgewell/sourcemap-codec 1.4.15 x 795 ops/sec ±0.25% (98 runs sampled)
|
|---|
| 96 | encode: sourcemap-codec x 231 ops/sec ±0.83% (86 runs sampled)
|
|---|
| 97 | encode: source-map-0.6.1 x 166 ops/sec ±0.57% (86 runs sampled)
|
|---|
| 98 | encode: source-map-0.8.0 x 203 ops/sec ±0.45% (88 runs sampled)
|
|---|
| 99 | Fastest is encode: local code,encode: @jridgewell/sourcemap-codec 1.4.15
|
|---|
| 100 |
|
|---|
| 101 |
|
|---|
| 102 | ***
|
|---|
| 103 |
|
|---|
| 104 |
|
|---|
| 105 | babel.min.js.map - 347793 segments
|
|---|
| 106 |
|
|---|
| 107 | Decode Memory Usage:
|
|---|
| 108 | local code 35424960 bytes
|
|---|
| 109 | @jridgewell/sourcemap-codec 1.4.15 35424696 bytes
|
|---|
| 110 | sourcemap-codec 36033464 bytes
|
|---|
| 111 | source-map-0.6.1 62253704 bytes
|
|---|
| 112 | source-map-0.8.0 43843920 bytes
|
|---|
| 113 | chrome dev tools 45111400 bytes
|
|---|
| 114 | Smallest memory usage is @jridgewell/sourcemap-codec 1.4.15
|
|---|
| 115 |
|
|---|
| 116 | Decode speed:
|
|---|
| 117 | decode: local code x 38.18 ops/sec ±5.44% (52 runs sampled)
|
|---|
| 118 | decode: @jridgewell/sourcemap-codec 1.4.15 x 38.36 ops/sec ±5.02% (52 runs sampled)
|
|---|
| 119 | decode: sourcemap-codec x 34.05 ops/sec ±4.45% (47 runs sampled)
|
|---|
| 120 | decode: source-map-0.6.1 x 4.31 ops/sec ±2.76% (15 runs sampled)
|
|---|
| 121 | decode: source-map-0.8.0 x 55.60 ops/sec ±0.13% (73 runs sampled)
|
|---|
| 122 | chrome dev tools x 16.94 ops/sec ±3.78% (46 runs sampled)
|
|---|
| 123 | Fastest is decode: source-map-0.8.0
|
|---|
| 124 |
|
|---|
| 125 | Encode Memory Usage:
|
|---|
| 126 | local code 2606016 bytes
|
|---|
| 127 | @jridgewell/sourcemap-codec 1.4.15 2626440 bytes
|
|---|
| 128 | sourcemap-codec 21152576 bytes
|
|---|
| 129 | source-map-0.6.1 25023928 bytes
|
|---|
| 130 | source-map-0.8.0 25256448 bytes
|
|---|
| 131 | Smallest memory usage is local code
|
|---|
| 132 |
|
|---|
| 133 | Encode speed:
|
|---|
| 134 | encode: local code x 127 ops/sec ±0.18% (83 runs sampled)
|
|---|
| 135 | encode: @jridgewell/sourcemap-codec 1.4.15 x 128 ops/sec ±0.26% (83 runs sampled)
|
|---|
| 136 | encode: sourcemap-codec x 29.31 ops/sec ±2.55% (53 runs sampled)
|
|---|
| 137 | encode: source-map-0.6.1 x 18.85 ops/sec ±3.19% (36 runs sampled)
|
|---|
| 138 | encode: source-map-0.8.0 x 19.34 ops/sec ±1.97% (36 runs sampled)
|
|---|
| 139 | Fastest is encode: @jridgewell/sourcemap-codec 1.4.15
|
|---|
| 140 |
|
|---|
| 141 |
|
|---|
| 142 | ***
|
|---|
| 143 |
|
|---|
| 144 |
|
|---|
| 145 | preact.js.map - 1992 segments
|
|---|
| 146 |
|
|---|
| 147 | Decode Memory Usage:
|
|---|
| 148 | local code 261696 bytes
|
|---|
| 149 | @jridgewell/sourcemap-codec 1.4.15 244296 bytes
|
|---|
| 150 | sourcemap-codec 302816 bytes
|
|---|
| 151 | source-map-0.6.1 939176 bytes
|
|---|
| 152 | source-map-0.8.0 336 bytes
|
|---|
| 153 | chrome dev tools 587368 bytes
|
|---|
| 154 | Smallest memory usage is source-map-0.8.0
|
|---|
| 155 |
|
|---|
| 156 | Decode speed:
|
|---|
| 157 | decode: local code x 17,782 ops/sec ±0.32% (97 runs sampled)
|
|---|
| 158 | decode: @jridgewell/sourcemap-codec 1.4.15 x 17,863 ops/sec ±0.40% (100 runs sampled)
|
|---|
| 159 | decode: sourcemap-codec x 12,453 ops/sec ±0.27% (101 runs sampled)
|
|---|
| 160 | decode: source-map-0.6.1 x 1,288 ops/sec ±1.05% (96 runs sampled)
|
|---|
| 161 | decode: source-map-0.8.0 x 9,289 ops/sec ±0.27% (101 runs sampled)
|
|---|
| 162 | chrome dev tools x 4,769 ops/sec ±0.18% (100 runs sampled)
|
|---|
| 163 | Fastest is decode: @jridgewell/sourcemap-codec 1.4.15
|
|---|
| 164 |
|
|---|
| 165 | Encode Memory Usage:
|
|---|
| 166 | local code 262944 bytes
|
|---|
| 167 | @jridgewell/sourcemap-codec 1.4.15 25544 bytes
|
|---|
| 168 | sourcemap-codec 323048 bytes
|
|---|
| 169 | source-map-0.6.1 507808 bytes
|
|---|
| 170 | source-map-0.8.0 507480 bytes
|
|---|
| 171 | Smallest memory usage is @jridgewell/sourcemap-codec 1.4.15
|
|---|
| 172 |
|
|---|
| 173 | Encode speed:
|
|---|
| 174 | encode: local code x 24,207 ops/sec ±0.79% (95 runs sampled)
|
|---|
| 175 | encode: @jridgewell/sourcemap-codec 1.4.15 x 24,288 ops/sec ±0.48% (96 runs sampled)
|
|---|
| 176 | encode: sourcemap-codec x 6,761 ops/sec ±0.21% (100 runs sampled)
|
|---|
| 177 | encode: source-map-0.6.1 x 5,374 ops/sec ±0.17% (99 runs sampled)
|
|---|
| 178 | encode: source-map-0.8.0 x 5,633 ops/sec ±0.32% (99 runs sampled)
|
|---|
| 179 | Fastest is encode: @jridgewell/sourcemap-codec 1.4.15,encode: local code
|
|---|
| 180 |
|
|---|
| 181 |
|
|---|
| 182 | ***
|
|---|
| 183 |
|
|---|
| 184 |
|
|---|
| 185 | react.js.map - 5726 segments
|
|---|
| 186 |
|
|---|
| 187 | Decode Memory Usage:
|
|---|
| 188 | local code 678816 bytes
|
|---|
| 189 | @jridgewell/sourcemap-codec 1.4.15 678816 bytes
|
|---|
| 190 | sourcemap-codec 816400 bytes
|
|---|
| 191 | source-map-0.6.1 2288864 bytes
|
|---|
| 192 | source-map-0.8.0 721360 bytes
|
|---|
| 193 | chrome dev tools 1012512 bytes
|
|---|
| 194 | Smallest memory usage is local code
|
|---|
| 195 |
|
|---|
| 196 | Decode speed:
|
|---|
| 197 | decode: local code x 6,178 ops/sec ±0.19% (98 runs sampled)
|
|---|
| 198 | decode: @jridgewell/sourcemap-codec 1.4.15 x 6,261 ops/sec ±0.22% (100 runs sampled)
|
|---|
| 199 | decode: sourcemap-codec x 4,472 ops/sec ±0.90% (99 runs sampled)
|
|---|
| 200 | decode: source-map-0.6.1 x 449 ops/sec ±0.31% (95 runs sampled)
|
|---|
| 201 | decode: source-map-0.8.0 x 3,219 ops/sec ±0.13% (100 runs sampled)
|
|---|
| 202 | chrome dev tools x 1,743 ops/sec ±0.20% (99 runs sampled)
|
|---|
| 203 | Fastest is decode: @jridgewell/sourcemap-codec 1.4.15
|
|---|
| 204 |
|
|---|
| 205 | Encode Memory Usage:
|
|---|
| 206 | local code 140960 bytes
|
|---|
| 207 | @jridgewell/sourcemap-codec 1.4.15 159808 bytes
|
|---|
| 208 | sourcemap-codec 969304 bytes
|
|---|
| 209 | source-map-0.6.1 930520 bytes
|
|---|
| 210 | source-map-0.8.0 930248 bytes
|
|---|
| 211 | Smallest memory usage is local code
|
|---|
| 212 |
|
|---|
| 213 | Encode speed:
|
|---|
| 214 | encode: local code x 8,013 ops/sec ±0.19% (100 runs sampled)
|
|---|
| 215 | encode: @jridgewell/sourcemap-codec 1.4.15 x 7,989 ops/sec ±0.20% (101 runs sampled)
|
|---|
| 216 | encode: sourcemap-codec x 2,472 ops/sec ±0.21% (99 runs sampled)
|
|---|
| 217 | encode: source-map-0.6.1 x 2,200 ops/sec ±0.17% (99 runs sampled)
|
|---|
| 218 | encode: source-map-0.8.0 x 2,220 ops/sec ±0.37% (99 runs sampled)
|
|---|
| 219 | Fastest is encode: local code
|
|---|
| 220 |
|
|---|
| 221 |
|
|---|
| 222 | ***
|
|---|
| 223 |
|
|---|
| 224 |
|
|---|
| 225 | vscode.map - 2141001 segments
|
|---|
| 226 |
|
|---|
| 227 | Decode Memory Usage:
|
|---|
| 228 | local code 198955264 bytes
|
|---|
| 229 | @jridgewell/sourcemap-codec 1.4.15 199175352 bytes
|
|---|
| 230 | sourcemap-codec 199102688 bytes
|
|---|
| 231 | source-map-0.6.1 386323432 bytes
|
|---|
| 232 | source-map-0.8.0 244116432 bytes
|
|---|
| 233 | chrome dev tools 293734280 bytes
|
|---|
| 234 | Smallest memory usage is local code
|
|---|
| 235 |
|
|---|
| 236 | Decode speed:
|
|---|
| 237 | decode: local code x 3.90 ops/sec ±22.21% (15 runs sampled)
|
|---|
| 238 | decode: @jridgewell/sourcemap-codec 1.4.15 x 3.95 ops/sec ±23.53% (15 runs sampled)
|
|---|
| 239 | decode: sourcemap-codec x 3.82 ops/sec ±17.94% (14 runs sampled)
|
|---|
| 240 | decode: source-map-0.6.1 x 0.61 ops/sec ±7.81% (6 runs sampled)
|
|---|
| 241 | decode: source-map-0.8.0 x 9.54 ops/sec ±0.28% (28 runs sampled)
|
|---|
| 242 | chrome dev tools x 2.18 ops/sec ±10.58% (10 runs sampled)
|
|---|
| 243 | Fastest is decode: source-map-0.8.0
|
|---|
| 244 |
|
|---|
| 245 | Encode Memory Usage:
|
|---|
| 246 | local code 13509880 bytes
|
|---|
| 247 | @jridgewell/sourcemap-codec 1.4.15 13537648 bytes
|
|---|
| 248 | sourcemap-codec 32540104 bytes
|
|---|
| 249 | source-map-0.6.1 127531040 bytes
|
|---|
| 250 | source-map-0.8.0 127535312 bytes
|
|---|
| 251 | Smallest memory usage is local code
|
|---|
| 252 |
|
|---|
| 253 | Encode speed:
|
|---|
| 254 | encode: local code x 20.10 ops/sec ±0.19% (38 runs sampled)
|
|---|
| 255 | encode: @jridgewell/sourcemap-codec 1.4.15 x 20.26 ops/sec ±0.32% (38 runs sampled)
|
|---|
| 256 | encode: sourcemap-codec x 5.44 ops/sec ±1.64% (18 runs sampled)
|
|---|
| 257 | encode: source-map-0.6.1 x 2.30 ops/sec ±4.79% (10 runs sampled)
|
|---|
| 258 | encode: source-map-0.8.0 x 2.46 ops/sec ±6.53% (10 runs sampled)
|
|---|
| 259 | Fastest is encode: @jridgewell/sourcemap-codec 1.4.15
|
|---|
| 260 | ```
|
|---|
| 261 |
|
|---|
| 262 | # License
|
|---|
| 263 |
|
|---|
| 264 | MIT
|
|---|
