srcmap-codec 0.1.3

High-performance VLQ source map codec
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

# srcmap-codec

[![crates.io](https://img.shields.io/crates/v/srcmap-codec.svg)](https://crates.io/crates/srcmap-codec)
[![docs.rs](https://docs.rs/srcmap-codec/badge.svg)](https://docs.rs/srcmap-codec)
[![CI](https://github.com/BartWaardenburg/srcmap/actions/workflows/ci.yml/badge.svg)](https://github.com/BartWaardenburg/srcmap/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/BartWaardenburg/srcmap/badges/rust-coverage.json)](https://github.com/BartWaardenburg/srcmap/actions/workflows/coverage.yml)

High-performance VLQ source map codec for Rust.

Encodes and decodes source map `mappings` strings using the Base64 VLQ format specified in [ECMA-426](https://tc39.es/ecma426/) (Source Map v3). Drop-in Rust equivalent of [`@jridgewell/sourcemap-codec`](https://github.com/jridgewell/sourcemap-codec).

## Install

```toml
[dependencies]
srcmap-codec = "0.1"
```

## Usage

### Decode and encode mappings

```rust
use srcmap_codec::{decode, encode};

let mappings = decode("AAAA;AACA,EAAE").unwrap();
assert_eq!(mappings.len(), 2); // 2 lines
assert_eq!(mappings[0][0], vec![0, 0, 0, 0]); // first segment

let encoded = encode(&mappings);
assert_eq!(encoded, "AAAA;AACA,EAAE");
```

### Low-level VLQ primitives

```rust
use srcmap_codec::{vlq_decode, vlq_encode};

let mut buf = Vec::new();
vlq_encode(&mut buf, 42);

let (value, bytes_read) = vlq_decode(&buf, 0).unwrap();
assert_eq!(value, 42);
```

### Parallel encoding

Enable the `parallel` feature for multi-threaded encoding via [rayon](https://crates.io/crates/rayon). ~1.5x faster for large maps (5K+ lines).

```toml
[dependencies]
srcmap-codec = { version = "0.1", features = ["parallel"] }
```

```rust
use srcmap_codec::encode_parallel;

let encoded = encode_parallel(&mappings);
```

## API

| Function | Description |
|----------|-------------|
| `decode(mappings) -> Result<SourceMapMappings>` | Decode a VLQ mappings string into lines of segments |
| `encode(mappings) -> String` | Encode decoded mappings back to a VLQ string |
| `encode_parallel(mappings) -> String` | Parallel encoding via rayon (requires `parallel` feature) |
| `vlq_decode(bytes, offset) -> Result<(i64, usize)>` | Decode a single VLQ value at the given byte offset |
| `vlq_encode(buf, value)` | Encode a single VLQ value and append to buffer |

### Types

```rust
type Segment = Vec<i64>;          // 1, 4, or 5 fields
type Line = Vec<Segment>;         // segments on one generated line
type SourceMapMappings = Vec<Line>; // all lines
```

Segments have 1, 4, or 5 fields:
- **1 field:** `[generated_column]`
- **4 fields:** `[generated_column, source_index, original_line, original_column]`
- **5 fields:** `[generated_column, source_index, original_line, original_column, name_index]`

## Performance

Inlined VLQ decoder with a single-char fast path covering values -15..15 (~85% of real-world source map values).

## Part of [srcmap](https://github.com/BartWaardenburg/srcmap)

This crate is the foundation of the srcmap source map toolkit. See the [main repository](https://github.com/BartWaardenburg/srcmap) for the full suite including parser, generator, and remapping.

## License

MIT