Исходная карта

Это библиотека для генерации и использования исходного формата карты, описанного здесь .

Использовать с узлом

1
$ npm install source-map

Использование в Интернете

1
2
3
4
5
6
<script src="https://unpkg.com/source-map@0.7.2/dist/source-map.js"></script>
<script>
    sourceMap.SourceMapConsumer.initialize({
        "lib/mappings.wasm": "https://unpkg.com/source-map@0.7.2/lib/mappings.wasm"
    });
</script>

Примеры

Consuming a source map

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
const rawSourceMap = {
  version: 3,
  file: 'min.js',
  names: ['bar', 'baz', 'n'],
  sources: ['one.js', 'two.js'],
  sourceRoot: 'http://example.com/www/js/',
  mappings: 'CAAC,IAAI,IAAM,SAAUA,GAClB,OAAOC,IAAID;CCDb,IAAI,IAAM,SAAUE,GAClB,OAAOA'
};

const whatever = await SourceMapConsumer.with(rawSourceMap, null, consumer => {

  console.log(consumer.sources);
  // [ 'http://example.com/www/js/one.js',
  //   'http://example.com/www/js/two.js' ]

  console.log(consumer.originalPositionFor({
    line: 2,
    column: 28
  }));
  // { source: 'http://example.com/www/js/two.js',
  //   line: 2,
  //   column: 10,
  //   name: 'n' }

  console.log(consumer.generatedPositionFor({
    source: 'http://example.com/www/js/two.js',
    line: 2,
    column: 10
  }));
  // { line: 2, column: 28 }

  consumer.eachMapping(function (m) {
    // ...
  });

  return computeWhatever();
});

Generating a source map

Подробное руководство: компиляция в JavaScript и отладка с использованием карт исходного кода

С SourceNode (API высокого уровня)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
function compile(ast) {
  switch (ast.type) {
  case 'BinaryExpression':
    return new SourceNode(
      ast.location.line,
      ast.location.column,
      ast.location.source,
      [compile(ast.left), " + ", compile(ast.right)]
    );
  case 'Literal':
    return new SourceNode(
      ast.location.line,
      ast.location.column,
      ast.location.source,
      String(ast.value)
    );
  // ...
  default:
    throw new Error("Bad AST");
  }
}

var ast = parse("40 + 2", "add.js");
console.log(compile(ast).toStringWithSourceMap({
  file: 'add.js'
}));
// { code: '40 + 2',
//   map: [object SourceMapGenerator] }

С SourceMapGenerator (API низкого уровня)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
var map = new SourceMapGenerator({
  file: "source-mapped.js"
});

map.addMapping({
  generated: {
    line: 10,
    column: 35
  },
  source: "foo.js",
  original: {
    line: 33,
    column: 2
  },
  name: "christopher"
});

console.log(map.toString());
// '{"version":3,"file":"source-mapped.js","sources":["foo.js"],"names":["christopher"],"mappings":";;;;;;;;;mCAgCEA"}'

API

Получите ссылку на модуль:

1
2
3
4
5
6
7
8
// Node.js
var sourceMap = require('source-map');

// Browser builds
var sourceMap = window.sourceMap;

// Inside Firefox
const sourceMap = require("devtools/toolkit/sourcemap/source-map.js");

SourceMapConsumer

Экземпляр SourceMapConsumerпредставляет собой проанализированную исходную карту, которую мы можем запросить для получения информации об исходных позициях файла, указав ей позицию файла в сгенерированном источнике.

SourceMapConsumer.initialize (параметры)

При использовании SourceMapConsumerвне node.js, например в Интернете, ему необходимо знать, с какого URL-адреса загружать lib/mappings.wasm. Вы должны сообщить об этом, вызвав initializeперед созданием любого SourceMapConsumers.

Объект параметров имеет следующие свойства:

"lib/mappings.wasm": A, Stringсодержащий URL-адрес файла lib/mappings.wasm.

1
2
3sourceMap.SourceMapConsumer.initialize({
  "lib/mappings.wasm": "https://example.com/source-map/lib/mappings.wasm"
});

новый SourceMapConsumer (rawSourceMap)

Единственным параметром является необработанная исходная карта (либо в виде строки, которая может быть JSON.parse'd, либо в виде объекта). Согласно спецификации, исходные карты имеют следующие атрибуты:

version: какой версии исходной спецификации карты соответствует эта карта.
sources: массив URL-адресов исходных файлов.
names: Массив идентификаторов, на которые могут ссылаться отдельные сопоставления.
sourceRoot: необязательно. Корневой URL-адрес, от которого все источники являются относительными.
sourcesContent: Необязательно.Массив содержимого исходных исходных файлов.
mappings: строка VLQ в формате Base64, содержащая фактические сопоставления.
file: Необязательно.Сгенерированное имя файла, с которым связана эта исходная карта.

Возвращается обещание созданного потребителя карты исходного кода.

Когда метод SourceMapConsumerбольше не будет использоваться, вы должны вызвать его destroyметод.

1
2
3
const consumer = await new sourceMap.SourceMapConsumer(rawSourceMapJsonData);
doStuffWith(consumer);
consumer.destroy();

В качестве альтернативы вы можете использовать SourceMapConsumer.with, чтобы не помнить о вызове destroy.

SourceMapConsumer.with

Создайте новый SourceMapConsumerиз rawSourceMapи sourceMapUrl ( SourceMapConsumerподробности см. в конструкторе. Затем вызовите метод async function f(SourceMapConsumer) -> Tс вновь созданным потребителем, дождитесь fзавершения, вызовите destroyпотребителя и верните fвозвращаемое значение.

Вы не должны использовать потребителя после fзавершения!

Используя with, вам не нужно вручную вызывать destroyпотребителя, поскольку он будет вызван автоматически после fзавершения.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
const xSquared = await SourceMapConsumer.with(
  myRawSourceMap,
  null,
  async function (consumer) {
    // Use `consumer` inside here and don't worry about remembering
    // to call `destroy`.

    const x = await whatever(consumer);
    return x * x;
  }
);

// You may not use that `consumer` anymore out here; it has
// been destroyed. But you can use `xSquared`.
console.log(xSquared);

SourceMapConsumer.prototype.destroy()

Освободите связанные с потребителем карты источника данные Wasm, которыми управляете вручную.

1consumer.destroy();

В качестве альтернативы вы можете использовать SourceMapConsumer.with, чтобы не помнить о вызове destroy.

SourceMapConsumer.prototype.computeColumnSpans()

Вычислите последний столбец для каждого созданного сопоставления. Последний столбец является включающим.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// Before:
consumer.allGeneratedPositionsFor({ line: 2, source: "foo.coffee" })
// [ { line: 2,
//     column: 1 },
//   { line: 2,
//     column: 10 },
//   { line: 2,
//     column: 20 } ]

consumer.computeColumnSpans();

// After:
consumer.allGeneratedPositionsFor({ line: 2, source: "foo.coffee" })
// [ { line: 2,
//     column: 1,
//     lastColumn: 9 },
//   { line: 2,
//     column: 10,
//     lastColumn: 19 },
//   { line: 2,
//     column: 20,
//     lastColumn: Infinity } ]

SourceMapConsumer.prototype.originalPositionFor(generatedPosition)

Возвращает исходную информацию об исходном источнике, строке и столбце для предоставленных позиций строки и столбца сгенерированного источника. Единственным аргументом является объект со следующими свойствами:

line: номер строки в сгенерированном исходном коде.Номера строк в этой библиотеке начинаются с 1 (обратите внимание, что базовая спецификация исходной карты использует номера строк с отсчетом от 0 — эта библиотека обрабатывает перевод).
column: номер столбца в сгенерированном источнике. Номера столбцов в этой библиотеке начинаются с 0.
bias: либо SourceMapConsumer.GREATEST_LOWER_BOUNDили SourceMapConsumer.LEAST_UPPER_BOUND.Указывает, следует ли возвращать ближайший элемент, который меньше или больше искомого элемента, соответственно, если точный элемент не может быть найден.По умолчанию SourceMapConsumer.GREATEST_LOWER_BOUND.

и объект возвращается со следующими свойствами:

source: исходный исходный файл или значение NULL, если эта информация недоступна.
line: номер строки в исходном источнике или значение NULL, если эта информация недоступна.
column: номер столбца в исходном источнике или значение NULL, если эта информация недоступна.Номер столбца начинается с 0.
name: Исходный идентификатор или значение NULL, если эта информация недоступна.

1
2
3
4
5
6
7
8
9
10
11
consumer.originalPositionFor({ line: 2, column: 10 })
// { source: 'foo.coffee',
//   line: 2,
//   column: 2,
//   name: null }

consumer.originalPositionFor({ line: 99999999999999999, column: 999999999999999 })
// { source: null,
//   line: null,
//   column: null,
//   name: null }

SourceMapConsumer.prototype.generatedPositionFor(originalPosition)

Возвращает сгенерированную информацию о строке и столбце для исходного источника, предоставленных позиций строки и столбца. Единственным аргументом является объект со следующими свойствами:

source: имя файла исходного источника.
line: номер строки в исходном источнике.
column: номер столбца в исходном источнике.Номер столбца начинается с 0.

и объект возвращается со следующими свойствами:

line: номер строки в сгенерированном источнике или нулевой.Номер строки начинается с 1.
column: номер столбца в сгенерированном источнике или нулевой.Номер столбца начинается с 0.

1
2
3
consumer.generatedPositionFor({ source: "example.js", line: 2, column: 10 })
// { line: 1,
//   column: 56 }

SourceMapConsumer.prototype.allGeneratedPositionsFor(originalPosition)

Возвращает всю сгенерированную информацию о строках и столбцах для исходного источника, предоставленной строки и столбца. Если столбец не указан, возвращается все сопоставления, соответствующие либо строке, которую мы ищем, либо следующей ближайшей строке, которая имеет какие-либо сопоставления. В противном случае возвращается все сопоставления, соответствующие данной строке и либо столбцу, который мы ищем, либо следующему ближайшему столбцу, имеющему какие-либо смещения.

Единственным аргументом является объект со следующими свойствами:

source: имя файла исходного источника.
line: номер строки в исходном источнике.
column: Необязательно. Номер столбца в исходном источнике. Номер столбца начинается с 0.

и возвращается массив объектов, каждый со следующими свойствами:

line: номер строки в сгенерированном источнике или нулевой.Номер строки начинается с 1.
column: номер столбца в сгенерированном источнике или нулевой.Номер столбца начинается с 0.

1
2
3
4
5
6
7
consumer.allGeneratedpositionsfor({ line: 2, source: "foo.coffee" })
// [ { line: 2,
//     column: 1 },
//   { line: 2,
//     column: 10 },
//   { line: 2,
//     column: 20 } ]

SourceMapConsumer.prototype.hasContentsOfAllSources()

Возвращайте true, если у нас есть встроенный исходный контент для каждого источника, указанного в карте источников, в противном случае — false.

Другими словами, если этот метод возвращает true, то он consumer.sourceContentFor(s)будет успешным для каждого источника sв consumer.sources.

1
2
3
4
5
6
7
// ...
if (consumer.hasContentsOfAllSources()) {
  consumerReadyCallback(consumer);
} else {
  fetchSources(consumer, consumerReadyCallback);
}
// ...

SourceMapConsumer.prototype.sourceContentFor(source[, returnNullOnMissing])

Возвращает исходное содержимое для предоставленного источника. Единственным аргументом является URL-адрес исходного исходного файла.

Если исходное содержимое для данного источника не найдено, выдается ошибка. При необходимости передайте trueв качестве второго возвращаемого параметра null.

1
2
3
4
5
6
7
8
9
10
11consumer.sources
// [ "my-cool-lib.clj" ]

consumer.sourceContentFor("my-cool-lib.clj")
// "..."

consumer.sourceContentFor("this is not in the source map");
// Error: "this is not in the source map" is not in the source map

consumer.sourceContentFor("this is not in the source map", true);
// null

SourceMapConsumer.prototype.eachMapping(обратный вызов, контекст, порядок)

Выполните итерацию по каждому сопоставлению между исходным источником/строкой/столбцом и сгенерированной строкой/столбцом в этой исходной карте.

callback: функция, которая вызывается при каждом сопоставлении.{ source, generatedLine, generatedColumn, originalLine, originalColumn, name }
context: Необязательно. Если указано, этот объект будет значением при this каждом callbackвызове.
order: либо SourceMapConsumer.GENERATED_ORDERили SourceMapConsumer.ORIGINAL_ORDER.Указывает, хотите ли вы перебирать сопоставления, отсортированные по порядку строк/столбцов сгенерированного файла или порядку исходного/строки/столбца соответственно SourceMapConsumer.GENERATED_ORDER.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
consumer.eachMapping(function (m) { console.log(m); })
// ...
// { source: 'illmatic.js',
//   generatedLine: 1,
//   generatedColumn: 0,
//   originalLine: 1,
//   originalColumn: 0,
//   name: null }
// { source: 'illmatic.js',
//   generatedLine: 2,
//   generatedColumn: 0,
//   originalLine: 2,
//   originalColumn: 0,
//   name: null }
// ...

SourceMapGenerator

Экземпляр SourceMapGenerator представляет исходную карту, которая создается постепенно.

новый SourceMapGenerator([startOfSourceMap])

Вы можете передать объект со следующими свойствами:

file: имя файла сгенерированного источника, с которым связана эта исходная карта.
sourceRoot: корень для всех относительных URL-адресов в этой исходной карте.
skipValidation: Необязательно. Если true, отключает проверку сопоставлений по мере их добавления. Это может повысить производительность, но следует использовать с осторожностью, в крайнем случае. Даже в этом случае следует избегать использования этого флага при запуске тестов, если это возможно.

1
2
3
4
var generator = new sourceMap.SourceMapGenerator({
  file: "my-generated-javascript-file.js",
  sourceRoot: "http://example.com/app/js/"
});

SourceMapGenerator.fromSourceMap(sourceMapConsumer)

Создает новый SourceMapGeneratorиз существующего SourceMapConsumerэкземпляра.

sourceMapConsumerИсходная карта.

1
var generator = sourceMap.SourceMapGenerator.fromSourceMap(consumer);

SourceMapGenerator.prototype.addMapping(сопоставление)

Добавьте одно сопоставление из строки и столбца исходного источника в строку и столбец сгенерированного источника для создаваемой исходной карты. Объект сопоставления должен иметь следующие свойства:

generated: объект с сгенерированными позициями строк и столбцов.
original: объект с исходными позициями строк и столбцов.
source: Исходный исходный файл (относительно sourceRoot).
name: необязательное исходное имя токена для этого сопоставления.

1
2
3
4
5generator.addMapping({
  source: "module-one.scm",
  original: { line: 128, column: 0 },
  generated: { line: 3, column: 456 }
})

SourceMapGenerator.prototype.setSourceContent(sourceFile, sourceContent)

Установите исходное содержимое для исходного файла.

sourceFileURL-адрес исходного исходного файла.
sourceContentсодержимое исходного файла.

1
2
generator.setSourceContent("module-one.scm",
                           fs.readFileSync("path/to/module-one.scm"))

SourceMapGenerator.prototype.applySourceMap(sourceMapConsumer[, sourceFile[, sourceMapPath]])

Применяет SourceMap для исходного файла к SourceMap. Каждое сопоставление с предоставленным исходным файлом перезаписывается с использованием предоставленного SourceMap. Примечание. Разрешение результирующих сопоставлений является минимальным для этой карты и предоставленной карты.

sourceMapConsumer: SourceMap, который будет применен.
sourceFile: Необязательно. Имя исходного файла. Если опущено, будет использоваться sourceMapConsumer.file, если он существует. В противном случае будет выдана ошибка.
sourceMapPath: Необязательно. Имя пути к применяемой исходной карте. Если относительное, то оно относится к исходной карте.

Этот параметр необходим, когда два SourceMap не находятся в одном каталоге, а применяемый SourceMap содержит относительные исходные пути. Если это так, эти относительные исходные пути необходимо переписать относительно SourceMap.

Если этот параметр опущен, предполагается, что оба SourceMaps находятся в одном и том же каталоге, поэтому перезапись не требуется (поставка '.'имеет тот же эффект).

SourceMapGenerator.prototype.toString()

Преобразует генерируемую исходную карту в строку.

1
2generator.toString()
// '{"version":3,"sources":["module-one.scm"],"names":[],"mappings":"...snip...","file":"my-generated-javascript-file.js","sourceRoot":"http://example.com/app/js/"}'

SourceNode

SourceNodes предоставляют способ абстрагирования интерполяции и/или объединения фрагментов сгенерированного исходного кода JavaScript, сохраняя при этом информацию о строках и столбцах, связанных между этими фрагментами и исходным исходным кодом. Это полезно в качестве окончательного промежуточного представления, которое компилятор может использовать перед выводом. сгенерированный JS и исходная карта.

новый SourceNode([строка, столбец, источник[, фрагмент[, имя]]])

line: исходный номер строки, связанной с этим исходным узлом, или нулевой, если он не связан с исходной строкой.
column: исходный номер столбца, связанный с этим исходным узлом, или значение NULL, если он не связан с исходным столбцом.Номер столбца начинается с 0.
source: имя файла исходного источника; значение null, если имя файла не указано.
chunk: Необязательно. Немедленно передается в SourceNode.prototype.add, см. ниже.
name: Необязательно. Исходный идентификатор.

1
2
3
4
5
var node = new SourceNode(1, 2, "a.cpp", [
  new SourceNode(3, 4, "b.cpp", "extern int status;\n"),
  new SourceNode(5, 6, "c.cpp", "std::string* make_string(size_t n);\n"),
  new SourceNode(7, 8, "d.cpp", "int main(int argc, char** argv) {}\n"),
]);

SourceNode.fromStringWithSourceMap(код, sourceMapConsumer[, относительный путь])

Создает SourceNode из сгенерированного кода и SourceMapConsumer.

code:Сгенерированный код
sourceMapConsumerSourceMap для сгенерированного кода
relativePathНеобязательный путь, относительно которого sourceMapConsumer должны быть относительные источники.

1
2
const consumer = await new SourceMapConsumer(fs.readFileSync("path/to/my-file.js.map", "utf8"));
const node = SourceNode.fromStringWithSourceMap(fs.readFileSync("path/to/my-file.js"), consumer);

SourceNode.prototype.add(кусок)

Добавьте фрагмент сгенерированного JS в этот исходный узел.

chunk: фрагмент строки сгенерированного кода JS, другой экземпляр SourceNodeили массив, каждый элемент которого является одним из этих элементов.

1
2
3
node.add(" + ");
node.add(otherNode);
node.add([leftHandOperandNode, " + ", rightHandOperandNode]);

SourceNode.prototype.prepend(кусок)

Добавьте к этому исходному узлу кусок сгенерированного JS.

chunk: фрагмент строки сгенерированного кода JS, другой экземпляр SourceNodeили массив, каждый элемент которого является одним из этих элементов.

1
node.prepend("/** Build Id: f783haef86324gf **/\n\n");

SourceNode.prototype.setSourceContent(sourceFile, sourceContent)

Установите исходное содержимое для исходного файла. Оно будет добавлено в SourceMapполе sourcesContent.

sourceFile: имя исходного файла.
sourceContent: Содержимое исходного файла

1
2
node.setSourceContent("module-one.scm",
                      fs.readFileSync("path/to/module-one.scm"))

SourceNode.prototype.walk(fn)

Прогулка по дереву фрагментов JS в этом узле и его дочерних элементах. Функция ходьбы вызывается один раз для каждого фрагмента JS и передает этот фрагмент и расположение строки/столбца исходного связанного с ним источника.

fn: Функция обхода.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
var node = new SourceNode(1, 2, "a.js", [
  new SourceNode(3, 4, "b.js", "uno"),
  "dos",
  [
    "tres",
    new SourceNode(5, 6, "c.js", "quatro")
  ]
]);

node.walk(function (code, loc) { console.log("WALK:", code, loc); })
// WALK: uno { source: 'b.js', line: 3, column: 4, name: null }
// WALK: dos { source: 'a.js', line: 1, column: 2, name: null }
// WALK: tres { source: 'a.js', line: 1, column: 2, name: null }
// WALK: quatro { source: 'c.js', line: 5, column: 6, name: null }

SourceNode.prototype.walkSourceContents(fn)

Прогулка по дереву SourceNodes. Функция обхода вызывается для каждого содержимого исходного файла и получает имя файла и исходное содержимое.

fn: Функция обхода.

1
2
3
4
5
6
7
8
9
10
11
12
var a = new SourceNode(1, 2, "a.js", "generated from a");
a.setSourceContent("a.js", "original a");
var b = new SourceNode(1, 2, "b.js", "generated from b");
b.setSourceContent("b.js", "original b");
var c = new SourceNode(1, 2, "c.js", "generated from c");
c.setSourceContent("c.js", "original c");

var node = new SourceNode(null, null, null, [a, b, c]);
node.walkSourceContents(function (source, contents) { console.log("WALK:", source, ":", contents); })
// WALK: a.js : original a
// WALK: b.js : original b
// WALK: c.js : original c

SourceNode.prototype.join(сентябрь)

Аналогично Array.prototype.join, за исключением SourceNodes. Вставляет разделитель между каждым из дочерних узлов этого исходного узла.

sep: Сепаратор.

1
2
3
4
5
6
var lhs = new SourceNode(1, 2, "a.rs", "my_copy");
var operand = new SourceNode(3, 4, "a.rs", "=");
var rhs = new SourceNode(5, 6, "a.rs", "orig.clone()");

var node = new SourceNode(null, null, null, [ lhs, operand, rhs ]);
var joinedNode = node.join(" ");

SourceNode.prototype.replaceRight(шаблон, замена)

Вызов String.prototype.replaceсамого правого фрагмента исходного кода. Полезно для обрезки пробелов в конце исходного узла и т. д.

pattern: шаблон для замены.
replacement: вещь, на которую можно заменить шаблон.

1
2
// Trim trailing white space.
node.replaceRight(/\s*$/, "");

SourceNode.prototype.toString()

Возвращает строковое представление этого исходного узла. Проходит по дереву и объединяет все различные фрагменты в одну строку.

1
2
3
4
5
6
7
8
9
10
11
var node = new SourceNode(1, 2, "a.js", [
  new SourceNode(3, 4, "b.js", "uno"),
  "dos",
  [
    "tres",
    new SourceNode(5, 6, "c.js", "quatro")
  ]
]);

node.toString()
// 'unodostresquatro'

SourceNode.prototype.toStringWithSourceMap([startOfSourceMap])

Возвращает строковое представление этого дерева исходных узлов, а также SourceMapGenerator, который содержит все сопоставления между сгенерированным и исходным источниками.

Аргументы те же, что и для new SourceMapGenerator.

1
2
3
4
5
6
7
8
9
10
11
12
var node = new SourceNode(1, 2, "a.js", [
  new SourceNode(3, 4, "b.js", "uno"),
  "dos",
  [
    "tres",
    new SourceNode(5, 6, "c.js", "quatro")
  ]
]);

node.toStringWithSourceMap({ file: "my-output-file.js" })
// { code: 'unodostresquatro',
//   map: [object SourceMapGenerator] }

Руководство по разработке

Базовый модуль

встроенные объекты

модуль сообщества