JS stdlib — source-map API

Member signatures use schematic object.member(...) API notation. Exported type declarations are valid TypeScript.

Portable Source Map v3 consumption across browsers, Node, Deno, and Bun.

Server runtimes use native source-map lookup after shared validation; browsers use the shared decoder directly. Every runtime returns the same normalized public result.

import SourceMap from "@rcompat/source-map";
import type {
  OriginalPosition, SourceMapPayload,
} from "@rcompat/source-map";

SourceMap#

A validated Source Map v3 consumer.

declare class SourceMap {}

Constructor#

new SourceMap()#

Creates a source-map consumer from an object or serialized JSON.

Parameters

input — Source Map v3 payload or its JSON representation.

Throws: TypeError when the payload or encoded mappings are invalid.

new SourceMap(input: SourceMapPayload | string)

Instance methods#

sourceMap.original()#

Finds the original position for a generated position.

Inputs and returned coordinates are one-based. The closest preceding segment on the same generated line applies until the next segment. Invalid positions, missing lines, and unmapped segments return undefined. Relative sources are resolved against sourceRoot; absolute source URLs remain unchanged. name appears only when the selected segment explicitly carries one.

Parameters

line — One-based generated line.
column — One-based generated column.

Returns: The normalized original position, or undefined when unmapped.

sourceMap.original(line: number, column: number): OriginalPosition | undefined

Example

const map = new SourceMap({
  version: 3,
  sources: ["input.ts"],
  names: [],
  mappings: "AAAA",
});
map.original(1, 1);
// { source: "input.ts", line: 1, column: 1 }

Types#

OriginalPosition#

A one-based original source position.

type OriginalPosition = {
  // One-based original column.
  column: number;
  // One-based original line.
  line: number;
  // Name attached explicitly to the selected mapping segment.
  name?: string;
  // Original source after applying `sourceRoot`, when present.
  source: string;
};

SourceMapPayload#

A Source Map v3 payload accepted by SourceMap.

type SourceMapPayload = {
  // Generated filename associated with the map.
  file?: string;
  // Base64 VLQ-encoded mapping segments.
  mappings: string;
  // Optional names referenced by mapping segments.
  names?: string[];
  // Optional root resolved against relative source entries.
  sourceRoot?: string;
  // Original source paths or URLs.
  sources: string[];
  // Optional source contents aligned one-to-one with `sources`.
  sourcesContent?: (string | null)[];
  // Source map format version; only version 3 is supported.
  version: 3;
};