@jridgewell/trace-mapping

@jridgewell/trace-mapping is a small, dependency-light library for consuming source maps: given a line and column in generated output, it resolves the original file, line, column, and symbol name the code came from (and the reverse lookup too). It reimplements the same originalPositionFor/generatedPositionFor API made popular by Mozilla’s source-map package, but does it in plain JavaScript/TypeScript instead of WebAssembly, which removes the async initialization step and cuts memory usage substantially on large maps.

It is one of five packages in the jridgewell/sourcemaps monorepo (alongside gen-mapping, remapping, source-map, and sourcemap-codec) and has become a de facto standard dependency inside the JavaScript build-tooling ecosystem — Babel, ESLint, esbuild-adjacent tooling, and many bundler plugins pull it in transitively for fast, synchronous sourcemap tracing.

What You Get

• TraceMap class that parses a raw or already-decoded source map object
• originalPositionFor / generatedPositionFor for line+column lookups in either direction
• traceSegment for direct access to the underlying mapping segment
• sourceContentFor to retrieve inlined sourcesContent for a given source
• AnyMap helper that normalizes both regular and sectioned (concatenated) source maps into a TraceMap
• isIgnored support for the x_google_ignoreList / ignore-list source map extension

Common Use Cases

• Mapping a browser stack trace or error line back to original TypeScript/JSX source
• Powering devtools-style “go to original source” features in bundlers and test runners
• Re-mapping positions when chaining multiple transform steps (e.g. Babel then Terser)
• Building custom source-map-aware tooling (coverage remapping, linters, profilers)

Under The Hood

Architecture: The library centers on a TraceMap class built by decoding a V3 source map’s base64-VLQ mappings string into flat typed arrays (src/flatten-map.ts, src/sourcemap-segment.ts), then sorting them by generated and by original position (src/by-source.ts, src/sort.ts) so both lookup directions can binary-search (src/binary-search.ts) in O(log n) instead of scanning. AnyMap (src/resolve.ts) sits in front of TraceMap to normalize the rarer sections-style concatenated map format into the same flat representation before handing off. Tech Stack: Pure TypeScript compiled to dual ESM/CJS output via a small shared esbuild script at the monorepo root, typed with hand-written .d.mts/.d.cts declarations rather than tsc-only emit; its only runtime dependencies are sibling monorepo packages @jridgewell/resolve-uri and @jridgewell/sourcemap-codec. Code Quality: Source is compact (~1,500 lines across 11 files) and each concern — sorting, resolving, flattening, binary search — lives in its own single-purpose module; the test/ directory mirrors this with dedicated suites plus mocha-run correctness tests and a prettier/eslint gate wired into npm test. API Design: The public surface (TraceMap, originalPositionFor, generatedPositionFor, traceSegment, sourceContentFor, isIgnored, AnyMap) mirrors the widely-known source-map package’s naming so it acts as a near drop-in replacement, minimizing the learning curve for anyone already familiar with that ecosystem.