magic_string/codec

Source Map v3 model and base64 VLQ codec.

generate_mappings turns a flat Segment list into the v3 mappings string; decode_mappings is its inverse. to_json serializes the whole SourceMap. See https://tc39.es/ecma426/ for the format.

Types

MapMode

</>

How a generated file should reference its source map.

pub type MapMode {
  External(url: String)
  Inline
  Hidden
}

Constructors

```
External(url: String)
```
Emit a sourceMappingURL comment pointing at a separate .map file.
```
Inline
```
Emit a sourceMappingURL comment with the whole map inlined as a base64 data: URI.
```
Hidden
```
Emit no comment (the map exists but is not referenced from the output).

Segment

</>

One mapping from a position in the generated output to a position in an original source. Half-open columns are UTF-16 code units; lines are zero-based. Inserted (synthesized) output produces no Segment.

pub type Segment {
  Segment(
    gen_line: Int,
    gen_col: Int,
    source_idx: Int,
    orig_line: Int,
    orig_col: Int,
  )
}

Constructors

Segment(
  gen_line: Int,
  gen_col: Int,
  source_idx: Int,
  orig_line: Int,
  orig_col: Int,
)

SourceMap

</>

A Source Map v3 document.

sources_content is positional with sources: each entry is the full original text of the source at the same index, or None when the content is not embedded (serialized as JSON null).

pub type SourceMap {
  SourceMap(
    version: Int,
    file: option.Option(String),
    source_root: option.Option(String),
    sources: List(String),
    sources_content: List(option.Option(String)),
    names: List(String),
    mappings: String,
  )
}

Constructors

SourceMap(
  version: Int,
  file: option.Option(String),
  source_root: option.Option(String),
  sources: List(String),
  sources_content: List(option.Option(String)),
  names: List(String),
  mappings: String,
)

Values

decode_mappings

</>

pub fn decode_mappings(
  mappings: String,
) -> Result(List(Segment), String)

Decode a Source Map v3 mappings string back to a flat Segment list. This is the inverse of generate_mappings: decode_mappings(generate_mappings(segs)) returns the same segments (in (gen_line, gen_col) order).

Only 4- and 5-field segments (those carrying a source pointer) are returned; 1-field segments (generated column only, no source) are skipped since Segment requires a source position. The optional 5th name field is decoded for delta-tracking but discarded (this codec does not model names).

decode_vlq

</>

pub fn decode_vlq(field: String) -> Result(List(Int), String)

Decode a single base64-VLQ field string back to its list of signed integers. This is the exact inverse of concatenating encode_vlq calls: decode_vlq(encode_vlq(a) <> encode_vlq(b)) == [a, b].

Returns Error when field contains a character outside the base64 alphabet, or ends mid-value (a continuation bit with no following digit).

encode_vlq

</>

pub fn encode_vlq(value: Int) -> String

Encode a single signed integer as a base64 VLQ string.

Sign is folded into the low bit (value << 1, or (-value << 1) | 1 for negatives), then the magnitude is split into 5-bit groups emitted low-group-first. Every group except the last carries the continuation bit (32); each resulting 6-bit value indexes into base64_alphabet.

generate_mappings

</>

pub fn generate_mappings(segments: List(Segment)) -> String

Build the Source Map v3 mappings string from a flat segment list.

Output lines are ;-separated and segments within a line are ,-separated. Each segment is the VLQ of four deltas: [gen_col, source_idx, orig_line, orig_col]. gen_col is delta’d within the line (reset to 0 per line); the other three are delta’d across the whole map. Inserted text contributes no segment (so a line with only inserted output is empty). hires is false: one segment per chunk.

to_json

</>

pub fn to_json(map: SourceMap) -> String

Serialize a SourceMap to a JSON string. file and sourceRoot are omitted when None; sourcesContent entries are null when None.

url_comment

</>

pub fn url_comment(map: SourceMap, mode: MapMode) -> String

Produce the sourceMappingURL comment for the given map and mode.

External points at a sibling .map URL, Inline embeds the whole map as a base64 data: URI, and Hidden emits nothing.