srcmap-sourcemap

High-performance source map parser and consumer for Rust.

Parses source map JSON and provides O(log n) position lookups. Implements the ECMA-426 Source Map v3 specification. Drop-in Rust equivalent of @jridgewell/trace-mapping.

Install

[dependencies]
srcmap-sourcemap = "0.3"

Usage

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

LazySourceMap

Types

Building From Decoded Parts

Compiler and coverage-instrumentation pipelines often already have source-map parts in memory: generated file, sources, names, source content, decoded mappings, ignore list, debug ID, and custom x_ extension fields. Use SourceMap::from_parts_with_extensions or SourceMap::builder() to pass those parts directly into srcmap-sourcemap without serializing to source-map JSON and parsing it back before lookup or srcmap-remapping composition.

For example, an Oxc-based coverage instrumenter can convert Oxc's emitted source-map fields into a SourceMap, apply preamble offsetting, and compose with an upstream inputSourceMap without using JSON as the interchange format.

use std::collections::HashMap;

use srcmap_sourcemap::{Mapping, SourceMap};

let mut extensions = HashMap::new();
extensions.insert("x_google_linecount".to_string(), serde_json::json!(1));

let sm = SourceMap::from_parts_with_extensions(
    Some("out.js".to_string()),
    None,
    vec!["src/input.ts".to_string()],
    vec![Some("export const value = 1;".to_string())],
    vec!["value".to_string()],
    vec![Mapping {
        generated_line: 0,
        generated_column: 0,
        source: 0,
        original_line: 0,
        original_column: 13,
        name: 0,
        is_range_mapping: false,
    }],
    vec![],
    None,
    None,
    extensions,
);

assert_eq!(sm.original_position_for(0, 0).unwrap().column, 13);

Runtime Coverage Offsets

V8 coverage ranges commonly start from generated UTF-8 byte offsets. Source-map lookups use generated line,column pairs where the column is a UTF-16 JavaScript code-unit offset. Build one GeneratedOffsetLookup per generated asset and reuse it for function ranges or beacon batches.

use srcmap_sourcemap::{GeneratedOffsetLookup, SourceMap};

let generated_code = "alpha();\nbeta();\n";
let map_json = r#"{
    "version": 3,
    "sources": ["input.ts"],
    "names": ["lineOne", "lineTwo"],
    "mappings": "AAAAA;AACAC"
}"#;

let sm = SourceMap::from_json(map_json).unwrap();
let lookup = GeneratedOffsetLookup::new(generated_code);

let start_offset = "alpha();\n".len() as u32;
let generated = lookup.byte_offset_to_position(start_offset).unwrap();
assert_eq!((generated.line, generated.column), (1, 0));

let original = lookup.original_position_for_offset(&sm, start_offset).unwrap();
assert_eq!(sm.source(original.source), "input.ts");
assert_eq!((original.line, original.column), (1, 0));

GeneratedOffsetLookup works with both SourceMap and LazySourceMap through the OriginalPositionLookup trait.

Free Functions

Fields

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 proposal) 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):

Part of srcmap

This crate is the core of the srcmap source map toolkit. See also:

• srcmap-codec - VLQ encode/decode
• srcmap-generator - Source map builder
• srcmap-remapping - Concatenation and composition

License

MIT