Trace the original position through a source map. 

Trace the original position through a source map

jridgewell

@jridgewell/trace-mapping

    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('@jridgewell/sourcemap-codec'), require('@jridgewell/resolve-uri')) :

    typeof define === 'function' && define.amd ? define(['exports', '@jridgewell/sourcemap-codec', '@jridgewell/resolve-uri'], factory) :

    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.traceMapping = {}, global.sourcemapCodec, global.resolveURI));

})(this, (function (exports, sourcemapCodec, resolveUri) { 'use strict';

    function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }

    var resolveUri__default = /*#__PURE__*/_interopDefaultLegacy(resolveUri);

        // The base is always treated as a directory, if it's not empty.

        // https://github.com/mozilla/source-map/blob/8cb3ee57/lib/util.js#L327

        // https://github.com/chromium/chromium/blob/da4adbb3/third_party/blink/renderer/devtools/front_end/sdk/SourceMap.js#L400-L401

        return resolveUri__default["default"](input, base);

     * Removes everything after the last "/", but leaves the slash.

        const index = path.lastIndexOf('/');

    function maybeSort(mappings, owned) {

        const unsortedIndex = nextUnsortedSegmentLine(mappings, 0);

        if (unsortedIndex === mappings.length)

        // If we own the array (meaning we parsed it from JSON), then we're free to directly mutate it. If

        // not, we do not want to modify the consumer's input array.

        for (let i = unsortedIndex; i < mappings.length; i = nextUnsortedSegmentLine(mappings, i + 1)) {

            mappings[i] = sortSegments(mappings[i], owned);

    function nextUnsortedSegmentLine(mappings, start) {

        for (let i = start; i < mappings.length; i++) {

        for (let j = 1; j < line.length; j++) {

            if (line[j][COLUMN] < line[j - 1][COLUMN]) {

        return line.sort(sortComparator);

     * A binary search implementation that returns the index if a match is found.

     * If no match is found, then the left-index (the index associated with the item that comes just

     * before the desired index) is returned. To maintain proper sort order, a splice would happen at

     * const index = binarySearch(array, needle, (item, needle) => item - needle);

     * array.splice(index + 1, 0, needle);

     * assert.deepEqual(array, [1, 2, 3]);

    function binarySearch(haystack, needle, low, high) {

            const mid = low + ((high - low) >> 1);

            const cmp = haystack[mid][COLUMN] - needle;

     * Retrieves the source content for a particular source, if its found. Returns null if not.

     * A helper that skips sorting of the input map's mappings array, which can be expensive for larger

    exports.presortedDecodedMap = void 0;

     * Returns a sourcemap object (with decoded mappings) suitable for passing to a library that expects

     * a sourcemap, or to JSON.stringify.

     * Returns a sourcemap object (with encoded mappings) suitable for passing to a library that expects

            this._decodedMemo = memoizedState();

            this._bySourceMemos = undefined;

            const isString = typeof map === 'string';

            if (!isString && map._decodedMemo)

            const parsed = (isString ? JSON.parse(map) : map);

            const { version, file, names, sourceRoot, sources, sourcesContent } = parsed;

            this.sourceRoot = sourceRoot;

            this.sourcesContent = sourcesContent;

                const from = resolve(sourceRoot || '', stripFilename(mapUrl));

                this.resolvedSources = sources.map((s) => resolve(s || '', from));

                this.resolvedSources = sources.map((s) => s || '');

            if (typeof mappings === 'string') {

                this._encoded = mappings;

                this._decoded = undefined;

                this._encoded = undefined;

                this._decoded = maybeSort(mappings, isString);

        exports.encodedMappings = (map) => {

            return ((_a = map._encoded) !== null && _a !== void 0 ? _a : (map._encoded = sourcemapCodec.encode(map._decoded)));

        exports.decodedMappings = (map) => {

            return (map._decoded || (map._decoded = sourcemapCodec.decode(map._encoded)));

        exports.traceSegment = (map, line, column) => {

            const decoded = exports.decodedMappings(map);

            // It's common for parent source maps to have pointers to lines that have no

            // mapping (like a "//# sourceMappingURL=") at the end of the child file.

            return traceSegmentInternal(decoded[line], map._decodedMemo, line, column, GREATEST_LOWER_BOUND);

        exports.originalPositionFor = (map, { line, column, bias }) => {

                throw new Error(LINE_GTR_ZERO);

                throw new Error(COL_GTR_EQ_ZERO);

                return INVALID_ORIGINAL_MAPPING;

            const segment = traceSegmentInternal(decoded[line], map._decodedMemo, line, column, bias || GREATEST_LOWER_BOUND);

            const { names, resolvedSources } = map;

                source: resolvedSources[segment[SOURCES_INDEX]],

                line: segment[SOURCE_LINE] + 1,

                column: segment[SOURCE_COLUMN],

                name: segment.length === 5 ? names[segment[NAMES_INDEX]] : null,

        exports.generatedPositionFor = (map, { source, line, column, bias }) => {

            const { sources, resolvedSources } = map;

            let sourceIndex = sources.indexOf(source);

                sourceIndex = resolvedSources.indexOf(source);

                return INVALID_GENERATED_MAPPING;

            const generated = (map._bySources || (map._bySources = buildBySources(exports.decodedMappings(map), (map._bySourceMemos = sources.map(memoizedState)))));

        exports.sourceContentFor = (map, source) => {

            const { sources, resolvedSources, sourcesContent } = map;

            let index = sources.indexOf(source);

                index = resolvedSources.indexOf(source);

            return index === -1 ? null : sourcesContent[index];

        exports.presortedDecodedMap = (map, mapUrl) => {

            const clone = Object.assign({}, map);

            const tracer = new TraceMap(clone, mapUrl);

            tracer._decoded = map.mappings;

                sourceRoot: map.sourceRoot,

                sourcesContent: map.sourcesContent,

                mappings: exports.decodedMappings(map),

                mappings: exports.encodedMappings(map),

    function traceSegmentInternal(segments, memo, line, column, bias) {

        let index = memoizedBinarySearch(segments, column, memo, line);

            index = (bias === LEAST_UPPER_BOUND ? upperBound : lowerBound)(segments, column, index);

        else if (bias === LEAST_UPPER_BOUND)

        if (index === -1 || index === segments.length)

    exports.GREATEST_LOWER_BOUND = GREATEST_LOWER_BOUND;

    exports.LEAST_UPPER_BOUND = LEAST_UPPER_BOUND;

    Object.defineProperty(exports, '__esModule', { value: true });

//# sourceMappingURL=trace-mapping.umd.js.map

import type { SourceMapSegment } from './sourcemap-segment';

import type { SourceMapV3, DecodedSourceMap, EncodedSourceMap, InvalidOriginalMapping, OriginalMapping, InvalidGeneratedMapping, GeneratedMapping, SourceMapInput, Needle, SourceNeedle, SourceMap, EachMapping } from './types';

export type { SourceMapSegment } from './sourcemap-segment';

export type { SourceMapInput, SectionedSourceMapInput, DecodedSourceMap, EncodedSourceMap, SectionedSourceMap, InvalidOriginalMapping, OriginalMapping as Mapping, OriginalMapping, InvalidGeneratedMapping, GeneratedMapping, EachMapping, } from './types';

export declare const LEAST_UPPER_BOUND = -1;

export declare const GREATEST_LOWER_BOUND = 1;

 * Returns the encoded (VLQ string) form of the SourceMap's mappings field.

export declare let encodedMappings: (map: TraceMap) => EncodedSourceMap['mappings'];

 * Returns the decoded (array of lines of segments) form of the SourceMap's mappings field.

export declare let decodedMappings: (map: TraceMap) => Readonly<DecodedSourceMap['mappings']>;

 * A low-level API to find the segment associated with a generated line/column (think, from a

 * stack trace). Line and column here are 0-based, unlike `originalPositionFor`.

export declare let traceSegment: (map: TraceMap, line: number, column: number) => Readonly<SourceMapSegment> | null;

 * A higher-level API to find the source/line/column associated with a generated line/column

 * (think, from a stack trace). Line is 1-based, but column is 0-based, due to legacy behavior in

export declare let originalPositionFor: (map: TraceMap, needle: Needle) => OriginalMapping | InvalidOriginalMapping;

 * Finds the source/line/column directly after the mapping returned by originalPositionFor, provided

 * the found mapping is from the same source and line as the originalPositionFor mapping.

 * Eg, in the code `let id = 1`, `originalPositionAfter` could find the mapping associated with `1`

 * using the same needle that would return `id` when calling `originalPositionFor`.

export declare let generatedPositionFor: (map: TraceMap, needle: SourceNeedle) => GeneratedMapping | InvalidGeneratedMapping;

 * Iterates each mapping in generated position order.

export declare let eachMapping: (map: TraceMap, cb: (mapping: EachMapping) => void) => void;

 * Retrieves the source content for a particular source, if its found. Returns null if not.

export declare let sourceContentFor: (map: TraceMap, source: string) => string | null;

 * A helper that skips sorting of the input map's mappings array, which can be expensive for larger

export declare let presortedDecodedMap: (map: DecodedSourceMap, mapUrl?: string) => TraceMap;

 * Returns a sourcemap object (with decoded mappings) suitable for passing to a library that expects

export declare let decodedMap: (map: TraceMap) => Omit<DecodedSourceMap, 'mappings'> & {

    mappings: readonly SourceMapSegment[][];

 * Returns a sourcemap object (with encoded mappings) suitable for passing to a library that expects

export declare let encodedMap: (map: TraceMap) => EncodedSourceMap;

export declare class TraceMap implements SourceMap {

    sourceRoot: SourceMapV3['sourceRoot'];

    sourcesContent: SourceMapV3['sourcesContent'];

    constructor(map: SourceMapInput, mapUrl?: string | null);

  "description": "Trace the original position through a source map",

  "typings": "dist/types/trace-mapping.d.ts",

      "types": "./dist/types/trace-mapping.d.ts",

      "browser": "./dist/trace-mapping.umd.js",

      "require": "./dist/trace-mapping.umd.js",

      "import": "./dist/trace-mapping.mjs"

  "author": "Justin Ridgewell <justin@ridgewell.name>",

    "url": "git+https://github.com/jridgewell/trace-mapping.git"

    "benchmark": "run-s build:rollup benchmark:*",

    "benchmark:install": "cd benchmark && npm install",

    "benchmark:only": "node --expose-gc benchmark/index.mjs",

    "build:rollup": "rollup -c rollup.config.js",

    "build:ts": "tsc --project tsconfig.build.json",

    "lint:prettier": "npm run test:lint:prettier -- --write",

    "lint:ts": "npm run test:lint:ts -- --fix",

    "prepublishOnly": "npm run preversion",

    "test": "run-s -n test:lint test:only",

    "test:lint:prettier": "prettier --check '{src,test}/**/*.ts' '**/*.md'",

    "test:lint:ts": "eslint '{src,test}/**/*.ts'",

    "@rollup/plugin-typescript": "8.3.0",

    "@typescript-eslint/eslint-plugin": "5.10.0",

    "@typescript-eslint/parser": "5.10.0",

    "eslint-plugin-no-only-tests": "2.6.0",

    "@jridgewell/sourcemap-codec": "^1.4.10"

> Trace the original position through a source map

`trace-mapping` allows you to take the line and column of an output file and trace it to the

original location in the source file through a source map.

You may already be familiar with the [`source-map`][source-map] package's `SourceMapConsumer`. This

provides the same `originalPositionFor` and `generatedPositionFor` API, without requiring WASM.

import { TraceMap, originalPositionFor, generatedPositionFor } from '@jridgewell/trace-mapping';

  sourcesContent: ['content of input.js'],

// Lines start at line 1, columns at column 0.

const traced = originalPositionFor(tracer, { line: 1, column: 5 });

const content = sourceContentFor(tracer, traced.source);

assert.strictEqual(content, 'content for input.js');

const generated = generatedPositionFor(tracer, {

We also provide a lower level API to get the actual segment that matches our line and column. Unlike

`originalPositionFor`, `traceSegment` uses a 0-base for `line`:

import { traceSegment } from '@jridgewell/trace-mapping';

const traced = traceSegment(tracer, /* line */ 0, /* column */ 5);

// Segments are [outputColumn, sourcesIndex, sourceLine, sourceColumn, namesIndex]

// Again, line is 0-base and so is sourceLine

assert.deepEqual(traced, [5, 0, 41, 4, 0]);

The sourcemap spec defines a special `sections` field that's designed to handle concatenation of

output code with associated sourcemaps. This type of sourcemap is rarely used (no major build tool

produces it), but if you are hand coding a concatenation you may need it. We provide an `AnyMap`

helper that can receive either a regular sourcemap or a `SectionedSourceMap` and returns a

import { AnyMap } from '@jridgewell/trace-mapping';

const output = [fooOutput, barOutput].join('\n');

      // barOutput's sourcemap will not affect the first line, only the second

const traced = originalPositionFor(sectioned, {

trace-mapping decoded         562400 bytes

trace-mapping encoded        5706544 bytes

source-map-js               10717664 bytes

source-map-0.6.1            17446384 bytes

source-map-0.8.0             9701757 bytes

Smallest memory usage is trace-mapping decoded

trace-mapping:    decoded JSON input x 180 ops/sec ±0.34% (85 runs sampled)

trace-mapping:    encoded JSON input x 364 ops/sec ±1.77% (89 runs sampled)

		{
		"name": "@jridgewell/trace-mapping",
		"version": "0.3.10",
		"version": "0.3.11",
		"description": "Trace the original position through a source map",
		@@ -5,0 +5,0 @@ "keywords": [

		@@ -342,2 +342,6 @@ (function (global, factory) {
		/**
		* Retrieves the source content for a particular source, if its found. Returns null if not.
		*/
		exports.sourceContentFor = void 0;
		/**
		* A helper that skips sorting of the input map's mappings array, which can be expensive for larger
		@@ -487,2 +491,11 @@ * maps.
		};
		exports.sourceContentFor = (map, source) => {
		const { sources, resolvedSources, sourcesContent } = map;
		if (sourcesContent == null)
		return null;
		let index = sources.indexOf(source);
		if (index === -1)
		index = resolvedSources.indexOf(source);
		return index === -1 ? null : sourcesContent[index];
		};
		exports.presortedDecodedMap = (map, mapUrl) => {
		@@ -489,0 +502,0 @@ const clone = Object.assign({}, map);

		@@ -39,2 +39,6 @@ import type { SourceMapSegment } from './sourcemap-segment';
		/**
		* Retrieves the source content for a particular source, if its found. Returns null if not.
		*/
		export declare let sourceContentFor: (map: TraceMap, source: string) => string \| null;
		/**
		* A helper that skips sorting of the input map's mappings array, which can be expensive for larger
		@@ -41,0 +45,0 @@ * maps.

		@@ -20,3 +20,8 @@ # @jridgewell/trace-mapping
		```typescript
		import { TraceMap, originalPositionFor, generatedPositionFor } from '@jridgewell/trace-mapping';
		import {
		TraceMap,
		originalPositionFor,
		generatedPositionFor,
		sourceContentFor,
		} from '@jridgewell/trace-mapping';

		@@ -26,2 +31,3 @@ const tracer = new TraceMap({
		sources: ['input.js'],
		sourcesContent: ['content of input.js'],
		names: ['foo'],
		@@ -40,2 +46,5 @@ mappings: 'KAyCIA',

		const content = sourceContentFor(tracer, traced.source);
		assert.strictEqual(content, 'content for input.js');

		const generated = generatedPositionFor(tracer, {
		@@ -42,0 +51,0 @@ source: 'input.js',

Improved metrics