Удивительный модуль сообщества

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

Статус сборки

NPM

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

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

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 вне SourceMapConsumer node.js, например, в Интернете, ему необходимо знать, с какого URL-адреса загружать lib/mappings.wasm . Вы должны сообщить об этом, вызвав initialize прежде чем создавать какие-либо SourceMapConsumer .

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

  • "lib/mappings.wasm" : String содержащая URL-адрес файла lib/mappings.wasm .
1 2 3
sourceMap.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 новый новый SourceMapConsumer из rawSourceMap и sourceMapUrl (подробности о затем, а sourceMapUrl SourceMapConsumer конструктор sourceMapUrl см. В конструкторе SourceMapConsumer async function f(SourceMapConsumer) -> T с вновь 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, связанные с потребителем карты источника, которые управляются вручную.

1
consumer.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 (generatePosition)

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

  • line : номер строки в сгенерированном источнике. Номера строк в этой библиотеке основаны на 1 (обратите внимание, что базовая спецификация карты источника использует номера строк на основе 0, эта библиотека обрабатывает перевод).

  • column : Номер столбца в сгенерированном источнике. Номера столбцов в этой библиотеке начинаются с 0.

  • bias : либо SourceMapConsumer.GREATEST_LOWER_BOUND либо SourceMapConsumer.LEAST_UPPER_BOUND . Указывает, возвращать ли ближайший элемент, который меньше или больше того, который мы ищем, соответственно, если точный элемент не может быть найден. По умолчанию SourceMapConsumer.GREATEST_LOWER_BOUND .

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

  • source : исходный исходный файл или ноль, если эта информация недоступна.

  • line : номер строки в исходном источнике или ноль, если эта информация недоступна. Номер строки начинается с 1.

  • column : номер столбца в исходном источнике или ноль, если эта информация недоступна. Номер столбца начинается с 0.

  • name : исходный идентификатор или ноль, если эта информация недоступна.

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 : номер строки в исходном источнике. Номер строки начинается с 1.

  • 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 : номер строки в исходном источнике. Номер строки начинается с 1.

  • 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 11
consumer.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 } линия { 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 : Необязательно. При 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 SourceMap.
1
var generator = sourceMap.SourceMapGenerator.fromSourceMap(consumer);

SourceMapGenerator.prototype.addMapping (отображение)

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

  • generated : объект с сгенерированной позицией строки и столбца.

  • original : объект с исходной позицией строки и столбца.

  • source : исходный исходный файл (относительно sourceRoot).

  • name : необязательное оригинальное имя токена для этого сопоставления.

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

SourceMapGenerator.prototype.setSourceContent (sourceFile, sourceContent)

Установите исходный контент для исходного исходного файла.

  • sourceFile URL исходного файла.

  • 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 : исходная карта, которая будет применена.

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

  • sourceMapPath : Необязательно. sourceMapPath пути к SourceMap, который будет применен. Если относительный, то он относительно SourceMap.

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

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

SourceMapGenerator.prototype.toString ()

Отображает исходную карту, сгенерированную в строку.

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

SourceNode

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

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

  • line : исходный номер строки, связанный с этим исходным узлом, или ноль, если он не связан с исходной строкой. Номер строки начинается с 1.

  • column : исходный номер столбца, связанный с этим исходным узлом, или ноль, если он не связан с исходным столбцом. Номер столбца начинается с 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 (code, sourceMapConsumer [,lativePath])

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

  • code : сгенерированный код

  • sourceMapConsumer SourceMap для сгенерированного кода

  • 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 (chunk)

Добавьте к этому исходному узлу кусок сгенерированного 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)

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

  • 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] }