README.md

@@ -40,8 +40,10 @@ We also provide a lower level API to get the actual segment that matches our lin
 `originalPositionFor`, `traceSegment` uses a 0-base for `line`:
 
 ```typescript
+import { originalPositionFor } from '@jridgewell/trace-mapping';
+
 // line is 0-base.
-const traced = originalPositionFor(tracer, /* line */ 0, /* column */ 5);
+const traced = traceSegment(tracer, /* line */ 0, /* column */ 5);
 
 // Segments are [outputColumn, sourcesIndex, sourceLine, sourceColumn, namesIndex]
 // Again, line is 0-base and so is sourceLine

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jridgewell/trace-mapping",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Trace the original position through a source map",
   "keywords": [
     "source",

src/trace-mapping.ts

@@ -10,11 +10,12 @@ import type {
   DecodedSourceMap,
   EncodedSourceMap,
   InvalidMapping,
-  Mapping,
+  OriginalMapping,
   SourceMapSegment,
   SourceMapInput,
   Needle,
   SourceMap,
+  EachMapping,
 } from './types';
 
 export type {
@@ -23,7 +24,9 @@ export type {
   DecodedSourceMap,
   EncodedSourceMap,
   InvalidMapping,
-  Mapping,
+  OriginalMapping as Mapping,
+  OriginalMapping,
+  EachMapping,
 } from './types';
 
 const INVALID_MAPPING: InvalidMapping = Object.freeze({
@@ -41,20 +44,29 @@ export let encodedMappings: (map: TraceMap) => EncodedSourceMap['mappings'];
 /**
  * Returns the decoded (array of lines of segments) form of the SourceMap's mappings field.
  */
-export let decodedMappings: (map: TraceMap) => DecodedSourceMap['mappings'];
+export 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 let traceSegment: (map: TraceMap, line: number, column: number) => SourceMapSegment | null;
+export 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
  * `source-map` library.
  */
-export let originalPositionFor: (map: TraceMap, needle: Needle) => Mapping | InvalidMapping;
+export let originalPositionFor: (map: TraceMap, needle: Needle) => OriginalMapping | InvalidMapping;
+
+/**
+ * Iterates each mapping in generated position order.
+ */
+export let eachMapping: (map: TraceMap, cb: (mapping: EachMapping) => void) => void;
 
 /**
  * A helper that skips sorting of the input map's mappings array, which can be expensive for larger
@@ -70,7 +82,7 @@ export class TraceMap implements SourceMap {
   declare sources: SourceMapV3['sources'];
   declare sourcesContent: SourceMapV3['sourcesContent'];
 
-  declare resolvedSources: SourceMapV3['sources'];
+  declare resolvedSources: string[];
   private declare _encoded: string | undefined;
   private declare _decoded: SourceMapSegment[][];
 
@@ -92,7 +104,7 @@ export class TraceMap implements SourceMap {
       const from = resolve(sourceRoot || '', stripFilename(mapUrl));
       this.resolvedSources = sources.map((s) => resolve(s || '', from));
     } else {
-      this.resolvedSources = sources;
+      this.resolvedSources = sources.map((s) => s || '');
     }
 
     const { mappings } = parsed;
@@ -148,6 +160,40 @@ export class TraceMap implements SourceMap {
       };
     };
 
+    eachMapping = (map, cb) => {
+      const decoded = map._decoded;
+      const { names, resolvedSources } = map;
+
+      for (let i = 0; i < decoded.length; i++) {
+        const line = decoded[i];
+        for (let j = 0; j < line.length; j++) {
+          const seg = line[j];
+
+          const generatedLine = i + 1;
+          const generatedColumn = seg[0];
+          let source = null;
+          let originalLine = null;
+          let originalColumn = null;
+          let name = null;
+          if (seg.length !== 1) {
+            source = resolvedSources[seg[1]];
+            originalLine = seg[2];
+            originalColumn = seg[3];
+          }
+          if (seg.length === 5) name = names[seg[4]];
+
+          cb({
+            generatedLine,
+            generatedColumn,
+            source,
+            originalLine,
+            originalColumn,
+            name,
+          } as EachMapping);
+        }
+      }
+    };
+
     presortedDecodedMap = (map, mapUrl) => {
       const clone = Object.assign({}, map);
       clone.mappings = [];

src/types.ts

@@ -26,7 +26,7 @@ export interface DecodedSourceMap extends SourceMapV3 {
   mappings: SourceMapSegment[][];
 }
 
-export type Mapping = {
+export type OriginalMapping = {
   source: string | null;
   line: number;
   column: number;
@@ -44,6 +44,24 @@ export type SourceMapInput = string | EncodedSourceMap | DecodedSourceMap;
 
 export type Needle = { line: number; column: number };
 
+export type EachMapping =
+  | {
+      generatedLine: number;
+      generatedColumn: number;
+      source: null;
+      originalLine: null;
+      originalColumn: null;
+      name: null;
+    }
+  | {
+      generatedLine: number;
+      generatedColumn: number;
+      source: string | null;
+      originalLine: number;
+      originalColumn: number;
+      name: string | null;
+    };
+
 export abstract class SourceMap {
   declare version: SourceMapV3['version'];
   declare file: SourceMapV3['file'];

test/trace-mapping.test.ts

@@ -10,10 +10,16 @@ import {
   traceSegment,
   originalPositionFor,
   presortedDecodedMap,
+  eachMapping,
 } from '../src/trace-mapping';
 
 import type { ExecutionContext } from 'ava';
-import type { SourceMapInput, EncodedSourceMap, DecodedSourceMap } from '../src/trace-mapping';
+import type {
+  SourceMapInput,
+  EncodedSourceMap,
+  DecodedSourceMap,
+  EachMapping,
+} from '../src/trace-mapping';
 
 describe('TraceMap', () => {
   const decodedMap: DecodedSourceMap = {
@@ -247,6 +253,36 @@ describe('TraceMap', () => {
     test('json encoded source map', macro, JSON.stringify(encoded));
   });
 
+  describe('eachMapping', () => {
+    const mappings = decodedMap.mappings.flatMap((line, i) => {
+      return line.map((seg): EachMapping => {
+        return {
+          generatedLine: i + 1,
+          generatedColumn: seg[0],
+          source: seg.length === 1 ? null : `https://astexplorer.net/${decodedMap.sources[seg[1]]}`,
+          originalLine: seg.length === 1 ? null : seg[2],
+          originalColumn: seg.length === 1 ? null : seg[3],
+          name: seg.length === 5 ? decodedMap.names[seg[4]] : null,
+        } as any;
+      });
+    });
+
+    const macro = test.macro((t: ExecutionContext<unknown>, map: SourceMapInput) => {
+      t.plan(mappings.length);
+
+      const tracer = new TraceMap(map);
+      let i = 0;
+      eachMapping(tracer, (mapping) => {
+        t.deepEqual(mapping, mappings[i++]);
+      });
+    });
+
+    test('decoded source map', macro, decodedMap);
+    test('json decoded source map', macro, JSON.stringify(decodedMap));
+    test('encoded source map', macro, encodedMap);
+    test('json encoded source map', macro, JSON.stringify(encodedMap));
+  });
+
   describe('presortedDecodedMap', () => {
     test('propagates decoded mappings without sorting', (t) => {
       const mappings = decodedMap.mappings.map((line) => {