@rcompat/source-map

A dependency-free Source Map v3 consumer with the same public result on Node, Bun, and Deno. Runtime-conditioned adapters use each runtime's native node:module source-map lookup for original locations. A small shared VLQ decoder validates mappings and normalizes names, missing mappings, and source roots; browser bundles use that decoder for locations too.

Installation#

bash

npm install @rcompat/source-map

bash

pnpm add @rcompat/source-map

bash

yarn add @rcompat/source-map

bash

bun add @rcompat/source-map

Usage#

import SourceMap from "@rcompat/source-map";

const map = new SourceMap({
  version: 3,
  sources: ["src/app.ts"],
  names: ["start"],
  mappings: "AAAAA",
});

map.original(1, 1);
// { source: "src/app.ts", line: 1, column: 1, name: "start" }

new SourceMap(JSON.stringify({
  version: 3,
  sources: ["app.ts"],
  sourceRoot: "file:///project/src/",
  mappings: "AAAA",
})).original(1, 1);
// { source: "file:///project/src/app.ts", line: 1, column: 1 }

Both generated inputs and returned original line/column numbers are one-based. The closest preceding segment on the same generated line applies until the next segment. Unmapped segments, lines with no mapping, and invalid input positions return undefined. Invalid map payloads and malformed VLQ segments throw TypeError during construction instead of yielding invalid positions.

sourceRoot is resolved against relative sources, normalizing . and .. in URL, relative-path, and absolute-path roots. Absolute source URLs remain unchanged. The optional name belongs only to a segment explicitly carrying a name; native consumers may retain a previous name, and Deno omits names, so the package normalizes them through the validated mappings. No native SourceMap type is part of the public API.