srcmap-sourcemap 0.2.0

High-performance source map parser and consumer
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
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

# srcmap-sourcemap

[![crates.io](https://img.shields.io/crates/v/srcmap-sourcemap.svg)](https://crates.io/crates/srcmap-sourcemap)
[![docs.rs](https://docs.rs/srcmap-sourcemap/badge.svg)](https://docs.rs/srcmap-sourcemap)
[![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 source map parser and consumer for Rust.

Parses source map JSON and provides O(log n) position lookups. Implements the [ECMA-426](https://tc39.es/ecma426/) Source Map v3 specification. Drop-in Rust equivalent of [`@jridgewell/trace-mapping`](https://github.com/jridgewell/trace-mapping).

## Install

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

## Usage

```rust
use srcmap_sourcemap::SourceMap;

let json = r#"{"version":3,"sources":["input.js"],"names":[],"mappings":"AAAA;AACA"}"#;
let sm = SourceMap::from_json(json).unwrap();

// Forward lookup: generated position -> original position (0-based)
let loc = sm.original_position_for(0, 0).unwrap();
assert_eq!(sm.source(loc.source), "input.js");
assert_eq!(loc.line, 0);
assert_eq!(loc.column, 0);

// Reverse lookup: original position -> generated position
let pos = sm.generated_position_for("input.js", 0, 0).unwrap();
assert_eq!(pos.line, 0);
assert_eq!(pos.column, 0);
```

## API

### `SourceMap`

| Method | Description |
|--------|-------------|
| `from_json(json) -> Result<SourceMap>` | Parse a source map from a JSON string (regular or indexed) |
| `from_parts(file, source_root, sources, ...) -> SourceMap` | Build from pre-decoded components and mappings |
| `from_vlq(mappings_str, sources, names, ...) -> Result<SourceMap>` | Build from pre-parsed components and a VLQ mappings string |
| `from_vlq_with_range_mappings(mappings_str, ..., range_mappings_str) -> Result<SourceMap>` | Build from VLQ mappings and optional range mappings strings |
| `from_json_lines(json, start_line, end_line) -> Result<SourceMap>` | Parse and decode only the given generated-line range |
| `original_position_for(line, col) -> Option<OriginalLocation>` | Look up original position for a generated position |
| `original_position_for_with_bias(line, col, bias) -> Option<OriginalLocation>` | Look up original position with explicit search bias |
| `generated_position_for(source, line, col) -> Option<GeneratedLocation>` | Reverse lookup: original position to generated position |
| `generated_position_for_with_bias(source, line, col, bias) -> Option<GeneratedLocation>` | Reverse lookup with explicit search bias |
| `all_generated_positions_for(source, line, col) -> Vec<GeneratedLocation>` | Find all generated positions for an original position |
| `map_range(start_line, start_col, end_line, end_col) -> Option<MappedRange>` | Map a generated range to its original range |
| `all_mappings() -> &[Mapping]` | All decoded mappings |
| `mappings_for_line(line) -> &[Mapping]` | Slice of mappings for a single generated line |
| `source(index) -> &str` | Resolve a source index to its filename |
| `name(index) -> &str` | Resolve a name index to its string |
| `source_index(name) -> Option<u32>` | Look up a source filename to its index |
| `line_count() -> usize` | Number of generated lines |
| `mapping_count() -> usize` | Total number of decoded mappings |
| `has_range_mappings() -> bool` | Whether any mappings are range mappings |
| `range_mapping_count() -> usize` | Number of range mappings |
| `encode_range_mappings() -> Option<String>` | Encode range mappings to VLQ string |
| `to_json() -> String` | Serialize the source map to JSON |
| `to_json_with_options(exclude_content) -> String` | Serialize to JSON, optionally excluding `sourcesContent` |

### `LazySourceMap`

| Method | Description |
|--------|-------------|
| `from_json(json) -> Result<LazySourceMap>` | Parse JSON eagerly but defer VLQ decoding |
| `decode_line(line) -> Result<Vec<Mapping>>` | Decode mappings for a single generated line on demand |
| `original_position_for(line, col) -> Option<OriginalLocation>` | Look up original position (decodes the line lazily) |
| `line_count() -> usize` | Number of generated lines |
| `source(index) -> &str` | Resolve a source index to its filename |
| `name(index) -> &str` | Resolve a name index to its string |
| `source_index(name) -> Option<u32>` | Look up a source filename to its index |
| `mappings_for_line(line) -> Vec<Mapping>` | Decoded mappings for a single generated line |
| `into_sourcemap() -> Result<SourceMap>` | Fully decode and convert to a `SourceMap` |

### Types

| Type | Description |
|------|-------------|
| `Mapping` | A single decoded mapping entry (28 bytes) |
| `OriginalLocation` | Result of a forward lookup (source, line, column, name) |
| `GeneratedLocation` | Result of a reverse lookup (line, column) |
| `MappedRange` | Original start/end positions for a generated range |
| `Bias` | Search bias: `GreatestLowerBound` or `LeastUpperBound` |
| `MappingsIter<'a>` | Zero-allocation streaming iterator over VLQ-encoded mappings |
| `SourceMappingUrl` | Parsed sourceMappingURL: `Inline(String)` or `External(String)` |
| `ParseError` | Errors that can occur during source map parsing |

### Free Functions

| Function | Description |
|----------|-------------|
| `parse_source_mapping_url(source) -> Option<SourceMappingUrl>` | Extract and parse a `sourceMappingURL` comment from source code |
| `validate_deep(sm) -> Vec<String>` | Deep structural validation with bounds and ordering checks |

### Fields

| Field | Type |
|-------|------|
| `sources` | `Vec<String>` |
| `sources_content` | `Vec<Option<String>>` |
| `names` | `Vec<String>` |
| `file` | `Option<String>` |
| `source_root` | `Option<String>` |
| `ignore_list` | `Vec<u32>` |
| `debug_id` | `Option<String>` |
| `extensions` | `HashMap<String, serde_json::Value>` |

## Features

- **O(log n) binary search** for both forward and reverse lookups
- **Flat 28-byte mapping structs** for cache-friendly iteration
- **Lazy reverse index** built on first `generated_position_for` call
- **Indexed source maps** (`sections`) with automatic flattening
- **Zero-copy JSON parsing** via borrowed mappings string
- **Range mappings** (`rangeMappings` field, ECMA-426 Stage 2) with cross-line delta lookup
- **Lazy iterator** (`MappingsIter`) for zero-allocation streaming over encoded mappings
- **Robust error handling** for malformed input

## Performance

Benchmarked on a 100K segment source map (Criterion):

| Operation | Time |
|-----------|------|
| Parse | 701 us |
| Single lookup | 3 ns |
| 1000x lookups | 5.8 us (5.8 ns/lookup) |

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

This crate is the core of the srcmap source map toolkit. See also:
- [`srcmap-codec`](https://crates.io/crates/srcmap-codec) - VLQ encode/decode
- [`srcmap-generator`](https://crates.io/crates/srcmap-generator) - Source map builder
- [`srcmap-remapping`](https://crates.io/crates/srcmap-remapping) - Concatenation and composition

## License

MIT