perf: optimize lazy source map lookups

Author: BartWaardenburg

benchmarks/real-world.mjs

@@ -18,6 +18,15 @@ const LOOKUP_COUNT = 1_000;
 const LOOKUP_MAX_COLUMN = 200;
 const LOOKUP_SEED = 0x5eed1234;
 
+const createOrderedLookups = (count, maxLine, descending) =>
+  Array.from({ length: count }, (_, index) => {
+    const line = Math.floor((index * maxLine) / count);
+    return {
+      line: descending ? maxLine - 1 - line : line,
+      column: (index * 13) % LOOKUP_MAX_COLUMN,
+    };
+  });
+
 // ── Load fixtures ────────────────────────────────────────────────
 
 const FIXTURES = [
@@ -172,6 +181,60 @@ for (const { name, json, size } of maps) {
   );
 }
 
+// ── Fast-lazy lookup order ───────────────────────────────────────
+
+console.log("\n--- Fast-Lazy Lookup Order ---\n");
+
+for (const { name, json, size, lines } of maps) {
+  console.log(`### ${name}\n`);
+
+  const midLine = Math.floor(lines / 2);
+  const patterns = [
+    { name: "ascending", lookups: createOrderedLookups(LOOKUP_COUNT, lines, false) },
+    { name: "descending", lookups: createOrderedLookups(LOOKUP_COUNT, lines, true) },
+    {
+      name: "repeated",
+      lookups: Array.from({ length: LOOKUP_COUNT }, () => ({ line: midLine, column: 20 })),
+    },
+    {
+      name: "randomized",
+      lookups: createDeterministicLookups(LOOKUP_COUNT, lines, LOOKUP_MAX_COLUMN, LOOKUP_SEED),
+    },
+  ].map((pattern) => ({ ...pattern, map: new FastSourceMap(json) }));
+
+  const isLargeMap = size > 1024 * 1024;
+  const bench = createBench({
+    warmupIterations: isLargeMap ? 5 : 20,
+    iterations: isLargeMap ? 50 : 200,
+  });
+  const prefix = `real_world_lazy_lookup_1000x[${name}]`;
+
+  for (const pattern of patterns) {
+    bench.add(`${prefix} ${pattern.name}`, () => {
+      for (const { line, column } of pattern.lookups) {
+        pattern.map.originalPositionFor(line, column);
+      }
+    });
+  }
+
+  await bench.run();
+
+  console.table(
+    bench.tasks.map((task) => ({
+      Name: task.name,
+      "ops/sec": Math.round(throughputHz(task)).toLocaleString(),
+      "avg (μs)": (latencyMeanMs(task) * 1000).toFixed(1),
+      "per lookup (ns)": Math.round(
+        (latencyMeanMs(task) * 1_000_000) / LOOKUP_COUNT,
+      ).toLocaleString(),
+    })),
+  );
+
+  for (const pattern of patterns) {
+    pattern.map.free();
+  }
+}
+
 // ── Single lookup ────────────────────────────────────────────────
 
 console.log("\n--- Single Lookup ---\n");

crates/sourcemap/benches/parse.rs

@@ -596,6 +596,58 @@ fn batch_lookup_input() -> BatchLookupInput {
     BatchLookupInput { sm, lookups }
 }
 
+struct LazyLookupInput {
+    sm: LazySourceMap,
+    lookups: Vec<(u32, u32)>,
+}
+
+const LAZY_LOOKUP_LINES: u32 = 500;
+const LAZY_LOOKUP_COUNT: u32 = 1_000;
+
+fn lazy_lookup_input(lookups: Vec<(u32, u32)>) -> LazyLookupInput {
+    let sm = LazySourceMap::from_json_fast(&json_medium()).unwrap();
+    LazyLookupInput { sm, lookups }
+}
+
+fn ascending_lazy_lookup_input() -> LazyLookupInput {
+    lazy_lookup_input(
+        (0..LAZY_LOOKUP_COUNT)
+            .map(|index| (index * LAZY_LOOKUP_LINES / LAZY_LOOKUP_COUNT, 30))
+            .collect(),
+    )
+}
+
+fn descending_lazy_lookup_input() -> LazyLookupInput {
+    lazy_lookup_input(
+        (0..LAZY_LOOKUP_COUNT)
+            .map(|index| {
+                (LAZY_LOOKUP_LINES - 1 - index * LAZY_LOOKUP_LINES / LAZY_LOOKUP_COUNT, 30)
+            })
+            .collect(),
+    )
+}
+
+fn repeated_lazy_lookup_input() -> LazyLookupInput {
+    lazy_lookup_input(vec![(LAZY_LOOKUP_LINES / 2, 30); LAZY_LOOKUP_COUNT as usize])
+}
+
+fn randomized_lazy_lookup_input() -> LazyLookupInput {
+    let mut state = 0x5eed_1234_u32;
+    let lookups = std::iter::repeat_with(|| {
+        state = state.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
+        (state % LAZY_LOOKUP_LINES, (state >> 16) % 200)
+    })
+    .take(LAZY_LOOKUP_COUNT as usize)
+    .collect();
+    lazy_lookup_input(lookups)
+}
+
+fn run_lazy_lookups(input: &mut LazyLookupInput) {
+    for &(line, column) in &input.lookups {
+        black_box(input.sm.original_position_for(black_box(line), black_box(column)));
+    }
+}
+
 fn bench_lookup(criterion: &mut Criterion) {
     bench_with_input(criterion, "lookup_single_original_position_for", lookup_input, |sm| {
         sm.original_position_for(black_box(250), black_box(30))
@@ -612,6 +664,33 @@ fn bench_lookup(criterion: &mut Criterion) {
     );
 }
 
+fn bench_lazy_lookup(criterion: &mut Criterion) {
+    bench_with_input(
+        criterion,
+        "lazy_lookup_1000x_ascending",
+        ascending_lazy_lookup_input,
+        run_lazy_lookups,
+    );
+    bench_with_input(
+        criterion,
+        "lazy_lookup_1000x_descending",
+        descending_lazy_lookup_input,
+        run_lazy_lookups,
+    );
+    bench_with_input(
+        criterion,
+        "lazy_lookup_1000x_repeated",
+        repeated_lazy_lookup_input,
+        run_lazy_lookups,
+    );
+    bench_with_input(
+        criterion,
+        "lazy_lookup_1000x_randomized",
+        randomized_lazy_lookup_input,
+        run_lazy_lookups,
+    );
+}
+
 fn bench_vlq_decode(criterion: &mut Criterion) {
     bench_with_input(criterion, "vlq_decode_large_mappings_only", json_large_no_content, |json| {
         SourceMap::from_json(black_box(json)).unwrap()
@@ -637,6 +716,7 @@ criterion_group!(
     bench_vlq_isolation,
     bench_json_only,
     bench_lookup,
+    bench_lazy_lookup,
     bench_vlq_decode,
 );
 criterion_main!(benches);

crates/sourcemap/src/lib.rs

@@ -23,7 +23,7 @@
 //! assert_eq!(pos.column, 0);
 //! ```
 
-use std::cell::{Cell, OnceCell, RefCell};
+use std::cell::{OnceCell, RefCell};
 use std::collections::HashMap;
 use std::fmt;
 use std::io;
@@ -32,6 +32,9 @@ use serde::Deserialize;
 use srcmap_codec::{DecodeError, vlq_encode_unsigned};
 use srcmap_scopes::{Binding, CallSite, GeneratedRange, OriginalScope, Position, ScopeInfo};
 
+#[cfg(test)]
+use std::cell::Cell;
+
 pub mod js_identifiers;
 pub mod offset_lookup;
 pub mod source_view;
@@ -1987,10 +1990,11 @@ pub struct LazySourceMap {
     /// If true, decode_line must decode sequentially from the start.
     fast_scan: bool,
 
-    /// Highest line fully decoded so far (for progressive decode in fast-scan mode).
-    /// VLQ state at the end of this line is stored in `decode_state`.
-    decode_watermark: Cell<u32>,
-    decode_state: Cell<VlqState>,
+    /// Cumulative VLQ states indexed by the next undecoded line.
+    state_checkpoints: RefCell<Vec<VlqState>>,
+
+    #[cfg(test)]
+    decode_work: Cell<u32>,
 }
 
 impl LazySourceMap {
@@ -2028,8 +2032,13 @@ impl LazySourceMap {
             decoded_lines: RefCell::new(HashMap::new()),
             source_map,
             fast_scan,
-            decode_watermark: Cell::new(0),
-            decode_state: Cell::new(VlqState::default()),
+            state_checkpoints: RefCell::new(if fast_scan {
+                vec![VlqState::default()]
+            } else {
+                Vec::new()
+            }),
+            #[cfg(test)]
+            decode_work: Cell::new(0),
         }
     }
 
@@ -2311,70 +2320,71 @@ impl LazySourceMap {
         Ok((mappings, state))
     }
 
-    /// Decode a single line's mappings on demand.
-    ///
-    /// Returns the cached result if the line has already been decoded.
-    /// The line index is 0-based.
-    pub fn decode_line(&self, line: u32) -> Result<Vec<Mapping>, DecodeError> {
-        // Check cache first
-        if let Some(cached) = self.decoded_lines.borrow().get(&line) {
-            return Ok(cached.clone());
+    fn ensure_line_decoded(&self, line: u32) -> Result<(), DecodeError> {
+        if self.decoded_lines.borrow().contains_key(&line) {
+            return Ok(());
         }
 
         let line_idx = line as usize;
         if line_idx >= self.line_info.len() {
-            return Ok(Vec::new());
+            return Ok(());
         }
 
         if self.fast_scan {
-            // In fast-scan mode, VLQ state is not pre-computed.
-            // Decode sequentially from the watermark (or line 0 for backward seeks).
-            // For both forward and backward walks, use cached lines where available
-            // and only walk VLQ bytes to compute state for already-decoded lines.
-            let watermark = self.decode_watermark.get();
-            let start = if line >= watermark { watermark } else { 0 };
-            let mut state = if line >= watermark {
-                self.decode_state.get()
-            } else {
-                VlqState { source_index: 0, original_line: 0, original_column: 0, name_index: 0 }
-            };
+            let mut checkpoints = self.state_checkpoints.borrow_mut();
+            let start = line_idx.min(checkpoints.len() - 1);
+            let mut state = checkpoints[start];
+
+            for current_line_idx in start..=line_idx {
+                #[cfg(test)]
+                self.decode_work.set(self.decode_work.get() + 1);
 
-            for l in start..=line {
-                let info = &self.line_info[l as usize];
-                if self.decoded_lines.borrow().contains_key(&l) {
+                let current_line = current_line_idx as u32;
+                let info = &self.line_info[current_line_idx];
+                if self.decoded_lines.borrow().contains_key(&current_line) {
                     // Already cached — just walk VLQ bytes to compute end-state
                     let bytes = self.raw_mappings.as_bytes();
                     state = walk_vlq_state(bytes, info.byte_offset, info.byte_end, state)?;
                 } else {
-                    let (mappings, new_state) = self.decode_line_with_state(l, state)?;
+                    let (mappings, new_state) = self.decode_line_with_state(current_line, state)?;
                     state = new_state;
-                    self.decoded_lines.borrow_mut().insert(l, mappings);
+                    self.decoded_lines.borrow_mut().insert(current_line, mappings);
                 }
-            }
 
-            // Update watermark (only advance, never regress)
-            if line + 1 > self.decode_watermark.get() {
-                self.decode_watermark.set(line + 1);
-                self.decode_state.set(state);
+                let next_line_idx = current_line_idx + 1;
+                if next_line_idx == checkpoints.len() {
+                    checkpoints.push(state);
+                } else {
+                    checkpoints[next_line_idx] = state;
+                }
             }
 
-            let cached = self.decoded_lines.borrow().get(&line).cloned();
-            return Ok(cached.unwrap_or_default());
+            return Ok(());
         }
 
-        // Normal mode: line_info has pre-computed VLQ state
         let state = self.line_info[line_idx].state;
         let (mappings, _) = self.decode_line_with_state(line, state)?;
-        self.decoded_lines.borrow_mut().insert(line, mappings.clone());
-        Ok(mappings)
+        self.decoded_lines.borrow_mut().insert(line, mappings);
+        Ok(())
+    }
+
+    /// Decode a single line's mappings on demand.
+    ///
+    /// Returns the cached result if the line has already been decoded.
+    /// The line index is 0-based.
+    pub fn decode_line(&self, line: u32) -> Result<Vec<Mapping>, DecodeError> {
+        self.ensure_line_decoded(line)?;
+        Ok(self.decoded_lines.borrow().get(&line).cloned().unwrap_or_default())
     }
 
     /// Look up the original source position for a generated position.
     ///
     /// Both `line` and `column` are 0-based.
     /// Returns `None` if no mapping exists or the mapping has no source.
     pub fn original_position_for(&self, line: u32, column: u32) -> Option<OriginalLocation> {
-        let line_mappings = self.decode_line(line).ok()?;
+        self.ensure_line_decoded(line).ok()?;
+        let decoded_lines = self.decoded_lines.borrow();
+        let line_mappings = decoded_lines.get(&line)?;
 
         if line_mappings.is_empty() {
             return None;
@@ -7292,6 +7302,43 @@ mod tests {
         assert_eq!(loc0.line, 0);
     }
 
+    #[test]
+    fn lazy_sourcemap_backward_cache_miss_resumes_from_checkpoint() {
+        let mappings = std::iter::repeat_n("AACA", 64).collect::<Vec<_>>().join(";");
+        let json =
+            format!(r#"{{"version":3,"sources":["a.js"],"names":[],"mappings":"{mappings}"}}"#);
+        let sm = LazySourceMap::from_json_fast(&json).unwrap();
+
+        sm.decode_line(63).unwrap();
+        sm.decoded_lines.borrow_mut().remove(&15);
+        sm.decode_work.set(0);
+
+        sm.decode_line(15).unwrap();
+
+        assert_eq!(sm.decode_work.get(), 1, "must resume at the line-15 checkpoint");
+    }
+
+    #[test]
+    fn lazy_sourcemap_fast_scan_matches_prescan_in_descending_and_randomized_order() {
+        let mappings = std::iter::repeat_n("AACA,CAAC", 64).collect::<Vec<_>>().join(";");
+        let json =
+            format!(r#"{{"version":3,"sources":["a.js"],"names":[],"mappings":"{mappings}"}}"#);
+        let fast = LazySourceMap::from_json_fast(&json).unwrap();
+        let prescan = LazySourceMap::from_json_no_content(&json).unwrap();
+        let position = |map: &LazySourceMap, line, column| {
+            map.original_position_for(line, column)
+                .map(|loc| (loc.source, loc.line, loc.column, loc.name))
+        };
+
+        for line in (0..64).rev() {
+            assert_eq!(position(&fast, line, 1), position(&prescan, line, 1));
+        }
+
+        for line in [17, 2, 61, 9, 42, 0, 31, 5, 63, 23, 17, 42] {
+            assert_eq!(position(&fast, line, 2), position(&prescan, line, 2));
+        }
+    }
+
     #[test]
     fn lazy_sourcemap_fast_scan_vs_prescan_consistency() {
         // Verify fast_scan and prescan produce identical lookup results